Anatomy
- Leading icon: (Optional) Left aligned icon that provides context to the CTA
- Label: (Optional) Short, descriptive call to action
- Container: Bounding element that holds content, color, and icons
- Trailing icon: (Optional) Right aligned icon that provides context to the CTA
Usage Guidelines
Buttons fall under different variants based on the priority level of the actions they trigger. Each of the below variants are associated with a button type.
Choose the button type based on the priority level of the call to action.
When to use this component
- Use primary buttons to show the key action on a page or view. Most pages should only have one primary action
- Use secondary buttons next to primary buttons to indicate alternative or less pronounced actions.
- Use default buttons for common actions and navigation.
- Use danger buttons for destructive or irreversible actions, such as deleting an account or canceling a subscription.
- Use a plain button for actions that are less prominent, optional, or independent from the primary and secondary actions on the screen. Their primary purpose is to offer an action without distracting the user from the main task at hand.
Leading icons
Leading icons can visually represent a button’s action to lessen the cognitive load for users. For instance, a bell icon may symbolize setting up notifications or alerts.
Trailing accessories
Trailing icons should be used in specific use cases as a nod to the interaction. Some examples are:
- arrows or chevrons denoting previous or next actions
- menu buttons where we use chevrons as a drop-down
These should be used more sparingly in left-to-right languages.
When not to use this component
Don't use buttons to take user to an external URL (outside the application). Use a Link instead.
Best Practices
Write clear and action-driven labels using sentence-case, such as “Add patient” or “Delete appointment”. Use verb + noun whenever is possible.
Don’t use all-caps or other text formats.
Use primary and secondary variants when grouping actions.
Don’t use multiple instances of the primary variant when grouping actions.
Use the plain variant for less important or less common actions on the screen.
Use icons for affordance clarity or to highlight the action that will be performed.
Use the danger variant for every destructive action you need to portray.
Don’t use any other button variant for destructive actions even if they are the primary action on the screen.
Keep the same button width in both loading and not loading mode. The length of the label and its icons will define it.
Don’t use icons for decorative purposes, or that don’t portray the buttons’ action. In those cases might be better to use only a label.
Use full-width buttons for actions in contained spaces like modals, bottom sheets, and at the bottom of forms or screens.
Do not use any other loading method, such as the progress bar, as the available space is quite diminished.
Use counters in buttons to provide meaningful feedback. For instance, showing the number of items that will be affected by the action.
Do not use counters in multiple buttons in the same context. This can overwhelm users and reduce the effectiveness of the feedback.
Don't make buttons full-width just because space is available. Button width should reflect the action's importance and relationship to nearby content. Full-width buttons work best for primary actions in contained spaces like modals, bottom sheets, or form submissions.
General Behavior
Text alignment
Button text can be centered, left, or right alignment depending on the feature needs.
Width
Buttons can fit to content or be full width. Choose the width based on context and the action's importance:
- Fit to content – Use for most buttons, especially in toolbars, headers, or when multiple actions are grouped together. This conserves space and helps users understand the relationship between actions.
- Full width – Use for primary actions in contained spaces like modals, bottom sheets, and form submissions, or when multiple actions of equal importance need to fill the available space (e.g., Back/Next in wizards).
States
Where's the disabled button?
We have made the conscious decision to not provide a disabled button for now. We firmly believe that most of the solutions that use a disabled button can be solved in many other simpler ways, for instance, by using validation, progressive disclosure, or lowering the actions per page to reduce the cognitive load. We enforce this for a few reasons:
- Using disabled buttons makes us wonder why the button is not available and how to enable it. This requires explicit explanation and therefore increases the complexity of the screen (we cannot just forbid the action and not explain what is happening).
- Showing disabled buttons when they cannot be enabled in any way is frustrating. It clutters the interface and confuses us since a solution is not possible.
- Accessibility. It’s also a silent agreement that a disabled button has a very poor contrast. Disabled buttons could additionally be confused with secondary or plain buttons and just make the whole experience only accessible to the ones that can see the difference.
Variants
Sizes
Mobile buttons come in three distinct heights.
Small
Use this size for lower-priority actions in tight spaces, where the button needs to be compact and less prominent than the main content.
Medium (default)
This is the standard size for the majority of actions, ensuring a comfortable tap target and prominence on the screen.
Large
Reserve this size for rare, standalone calls to action that serve as the single focus of the screen and require the highest level of visual emphasis.
Icon-only
Icon-only buttons can be used when you need to save space. See Icon Button button for more information
Text
Text & Icon
Counter
A Button should be used as a counter when the number being displayed is a direct result of the user's action on that button.
Styles
Primary
Secondary
Default
Danger
Plain
Content Guidelines
- Always write in sentence case. Sentence case is accessible and scannable.
- Keep accessibility and localization in mind – only some icons are universally understood. For example, a magnifying glass for “search,” or the plus symbol for “add”. Most icons are abstract to groups of users, so it’s best to support with copy where possible.
For further information, see the Content Styleguide.
Known Gaps
- Accessibility Guidelines
- To have disabled states or not to have disabled states …