Garden 9 is now available.
The website has been updated to the latest major version. View previous versions
Skip to main content
Design
Components
Patterns
    • Introduction
      • Overview
    • Patterns
      • Buttons
      • Copy
      • Drag and drop
      • Error handling
      • Filters
      • Loaders
      • Rich-text editor
      • Save
      • Tables
    Table of Contents
    • Anatomy
    • Formatting
      • Size
      • Alignment
      • Variations
    • States
      • Loading
      • Disabled
    • Flows
      • Buttons vs Anchor (links)
    • Content guidelines
    • Localization & internationalization
      • RTL (right-to-left)
    • Accessibility
      • Keyboard support
      • ARIA attributes

    Buttons

    A button is an element on a page or view that tells a user what they can do and triggers an action.

    Table of Contents
    • Anatomy
    • Formatting
      • Size
      • Alignment
      • Variations
    • States
      • Loading
      • Disabled
    • Flows
      • Buttons vs Anchor (links)
    • Content guidelines
    • Localization & internationalization
      • RTL (right-to-left)
    • Accessibility
      • Keyboard support
      • ARIA attributes

    Anatomy

    Usage of button types
    1. Primary buttons are for the most important action in a given view. Use one primary button per page or view.
    2. Default buttons are for secondary actions
    3. Basic buttons are for repetitive or deemphasized actions in a given view

    Formatting

    Size

    Button size plays a part in content and user interaction. Clear labels and visual signifiers such as shape, color, and size help communicate the types of actions available and their priority in the process.

    • The default button size is medium
    • Use small buttons on screens that have greater information density
    Do this
    • Use same size buttons and inputs in the same flow
    Not this
    • Avoid mixing and matching button and input sizes

    Alignment

    When a basic or default button is placed in conjunction with a primary button, the primary button should always be placed at the end.

    Do this
    • Ensure the primary button is placed at the end of the set of actions
    Not this
    • Avoid placing primary buttons at the start of action groupings

    Variations

    Media

    Buttons can contain media iconography positioned at the start or end, to provide additional context. Only use icons when necessary.

    Do this
    • Use task-specific verbs for button labels
    Not this
    • Do not use iconography in addition to labels when buttons are grouped

    Icon buttons

    Where possible, avoid using Icon buttons over Buttons with labels.

    Do this
    • Use buttons with labels to maximise inclusivity when using primary or secondary actions
    Not this
    • Avoid using icon buttons as primary or secondary actions where possible as their meaning can be open to interpretation

    States

    Loading

    Loading buttons display a Dots loader inside the button to show loading progress. The Dots loader appears after the user has initiated an action, signifying the site is loading the next action to occur. Buttons shouldn’t change size while loading.

    Toggle dark mode
    Set primary hue
    Toggle RTL
    Open in CodeSandbox
    Copy code
    View code

    Disabled

    A disabled button prevents user interaction. They don’t appear in the tab order, can’t receive focus, and may not be read aloud by a screen reader.

    If a button action might result in an error, it is preferable to show an error message than to disable the interaction altogether. Error messages can at least guide the user’s next action, while a disabled button provides no useful information. It can be frustrating if a user doesn’t know what mistake they made and how to proceed.

    Do this
    • Always keep buttons interactive
    • Add contextual, in-line error notifications that set people up for success
    Not this
    • Do not disable a button with no clear direction on how to move forward

    Flows

    Buttons vs Anchor (links)

    Buttons vs Anchor links
    1. Buttons trigger an action on a page or view
    2. Anchor (links) help users navigate from one location to another

    Content guidelines

    The button call-to-action (CTA) should guide the experience, not just finish a page. Typically, the CTA repeats the page heading when possible (e.g. “Add agent”). The phrase repetition confirms the action that will take place.

    Do this
    • Write labels as verbs
    • Communicate a single action per button
    • Use sentence case
    • Consider longer languages. Use 1-4 words and a maximum of 20 characters
    Not this
    • Avoid CTAs that lack context like “Yes,” “No,” or “Maybe”
    • Avoid calling out more than one action
    • Avoid ALL CAPS
    • Avoid articles, pronouns, and punctuation

    For more help with choosing the right verb, visit our actionable language guidelines.

    Localization & internationalization

    RTL (right-to-left)

    Actions need to accommodate different languages (making them wider or shorter) and both left-to-right and right-to-left direction. Keep in mind that the width of your actions will change and act accordingly.

    For RTL languages, the layout of the button is mirrored. Split buttons will automatically switch places for dropdown and label, whilst media elements such as icons will be placed on the right side of the text.

    Arabic RTL example

    Accessibility

    Keyboard support

    Users must be able to activate a button by pressing Enter or Space while the button has focus.

    ARIA attributes

    Buttons can have different states that benefit from ARIA attributes. Assistive technology will communicate these attributes to users, providing users with important context for and information about the user interface.

    Toggle buttons

    Toggle buttons utilize the aria-pressed attribute indicating the current “pressed” state. The attribute must be set to “false” when the button hasn’t been pressed, and then change to “true,” once it has.

    Icon buttons

    Icon buttons utilize the aria-label attribute to provide an accessible text label for the icon. Ensure the label is appropriately localized on implementation.

    Dropdown buttons

    When utilizing Dropdowns that leverage Buttons, the aria-expanded attribute is set on the Button to indicate if the Dropdown menu is expanded or collapsed, and whether or not its child elements are displayed or hidden. The attribute must be set to “false” when the menu is closed, and then change to “true” when the menu is open.

    A Button that opens a Dropdown menu must also have aria-controls set to the id of the expandable menu and aria-expanded set to the current state of the menu.

    Finally, a Button that opens a Dropdown menu must have aria-haspopup set to “true.”

    Additional resources

    • https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#accessibility_concerns
    • https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed
    • https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded
    • https://www.w3.org/WAI/ARIA/apg/patterns/button/
    • https://inclusive-components.design/toggle-button/
    • https://inclusive-components.design/menus-menu-buttons/
    Garden is the design system by Zendesk.
    BlogGitHubVersions
    © Zendesk 2024