Anatomy
- Icon: A symbol or character that supports a specific action or use case
- Container (optional): The area that contains the icon
Subcomponents
Usage
Use a button iconic for minor actions that the user accesses infrequently. Iconic buttons are smaller and lighter than text buttons, so they're useful for adding actions in small spaces. They also create a hierarchy in the display because iconic buttons have a lower priority when positioned next to text buttons.
In this example, the iconic buttons don’t visually compete with the main actions on the page.
Variants
Learn about button iconic and find out how to use it in your design.
Types
Choose an icon for the button that clearly identifies its use case. Remember to choose icons that are universal and consistent with existing patterns.
In this example, the “X” symbol is a button iconic. The “X” symbol is universally recognized as a method for closing a window.
Colors
A button iconic has the following different color variants: primary, secondary, and tertiary. Each variant has an individual style and a bare style.
| Variant | Default style | Bare style |
|---|---|---|
| Primary |  |
 |
| Secondary |  |
 |
| Tertiary |  |
 |
Primary
Use a primary button iconic for the key action in a workflow or component. This variant grabs the user's attention and stands out among all components in the display.
Secondary
Use a secondary button iconic when its action aids in the completion of a workflow. This variant has a neutral style that works well alongside other buttons.
Note: The secondary variant is the default option.
Tertiary
Use a tertiary button iconic for actions that are optional or of less importance to a workflow. This variant is visually light and muted, allowing other primary or secondary actions to stand out.
Sizes
A button iconic is available in the following sizes: small (sm), medium (md), and large (lg). Choose a size based on the available space and the action's importance.
Small
Medium
Note: medium is the default size.
Large
Configurations
Learn how to customize button iconic by configuring the available properties.
Presets and controllers
This component contains a preset configuration that automatically configures properties and event handlers for a component, making the component ready to work when you add it to a page. A preset is designed to suit a specific use case. However, you can override preset property values with a custom configuration if you find it necessary for your design. Preset values that you override aren’t upgraded when updates are available. If you don’t want to use the preset values provided, select the option to configure the component manually. You can apply one preset to a single instance of a component on a page. For more information, see Presets.
A preset is always associated with a controller, which acts as a data resource for the component. Controllers provide the configuration data and event bindings the component needs to function in your experience. By selecting a preset, the required controller is added to the page. By adding a controller to the page, any new applicable components will have that controller's preset. For more information about how controllers work, see Controllers. For instructions on using the data inspector to view the default presets for a component, see View properties and events in the Controller API.
Icon selection
You can select an icon from the library to use for your button iconic or choose not to use an icon.
Tooltip
You can configure text that appears in the tooltip. A tooltip describes the icon or action, and it only appears on hover
Design recommendations
Learn how to apply button iconic in your design
Iconic buttons convey a visual hierarchy by separating groups of buttons styles. In this example, the buttons appear in their order of importance, starting with button primary. The button iconic with the ellipses signifies there are additional actions a user can take.
Don't mix different button types together. This makes it difficult for the user to determine which actions are the most important.
Alignment and positioning
Group button iconic with similar button types. When placing them side by side, order the buttons based on their importance starting from the left. You can use the variant styles to help distinguish primary, secondary, and tertiary actions.
UI text guidelines
These are some recommendations for using text with button iconic:
- Use a tooltip to provide a label for the button that shows only an icon
- For example, a gear icon could have the tooltip “Settings”
- Use verbs to express what will happen when the person selects the button
- For example, a filter icon could have the tooltip “Create a filter”
Behavior
Learn how button iconic behaves when the display changes or a user interacts with the component.
States
| State | Primary variant | Secondary variant | Tertiary variant |
|---|---|---|---|
| Default |  |
 |
 |
| Hover |  |
 |
 |
| Pressed |  |
 |
 |
| Focus |  |
 |
 |
| Disabled |  |
 |
 |
Responsive behaviors
Learn how button iconic responds to changes in a container or display.
Overflow
Limit your designs to three iconic buttons or fewer in one area. If you put too many buttons in one area, it creates visual noise.
If you have more than three actions, use the overflow behavior to display additional options.
The overflow behavior turns the third button iconic into an overflow menu, represented by three dots. When a user selects this button, a dropdown menu displays to list all additional actions.
Usability
List complies with all internationalization and accessibility requirements.
Internationalization
When the display translates to a right-to-left (RTL) language, the actions and their order of importance flips. The iconic buttons align on the left, with the primary action farthest to the right. Any secondary actions appear to the left of the primary action.
In this example, the “Attach” button iconic (i.e. the paperclip) is the primary action for this card, and “Share” (i.e. the 3 connected dots) is the least important.
Accessibility
Learn how to access the actionable elements of list through keyboard interactions and screen readers.
Keyboard interactions
- Tab: Navigates to a button iconic; consider this when organizing actions in your display
- Enter: Launches the action
Screen readers
The circular button requires configuration of the aria-label attribute in the configAria property to be accessible using a screen reader.
Screen readers will read the tooltip associated with each button iconic. Remember to create tooltips that accurately state the iconic button's action.