Button

What is this?

Buttons triggers allow merchants to identify and start the most important actions in a container.

Variants

Button Sizes

Button With Icon

Disabled

Loading

Usage

import { Button } from '@vtex/admin-ui'

export function Example() {
  return <Button onClick={() => {}}>Admin UI Button</Button>
}

Props

Name	Type	Description	Required	Default
size	normal, large	Size of the button	🚫	normal
variant	primary, secondary, tertiary, critical, criticalSecondary, criticalTertiary, neutralTertiary	Button variant	🚫	primary
icon	ReactNode	Icon of the button	🚫	-
iconPosition	start, end	Position of the icon	🚫	start
disabled	boolean	Defines if the Button is disabled	🚫	false
loading	boolean	Defines if the Button is in loading state	🚫	false
csx	StyleProp	Defines component styles	🚫	{}

Best Practices

• Button has the role button.
• When Button is in a focused state, pressing Space and Enter triggers its action.
• If disabled prop is true, Button has disabled and aria-disabled attributes set to true.
• When using an Icon-only button, you must set the aria-label property to make it accessible. Check Design recommendations for more practices around Icon usage in buttons.

function Example() {
  return (
    <Button
      icon={<IconHeart title="Favorite" />}
      aria-label="Favorite button"
    />
  )
}

Components

When should I use the Link, the Tab, or the Menu component instead of the Button?

• Choose the Link component for navigation triggers inside a text paragraph that opens a new tab or changes the page’s address.
• Choose the Tab component for navigation triggers that alternate between related views within the same container.
• Choose the Menu component for action triggers that are rarely used or need to be repeated multiple times in a list.

Variants

When should a Button be primary, secondary, or tertiary?

This answer depends on research to understand how frequently merchants use an action. Even so, there are patterns you can follow:

• Primary Buttons are frequently triggered, secondary Buttons are occasionally triggered, and tertiary actions are rarely triggered.
• There should be only one primary action visible at a time.
• There should be only one secondary action in a group of actions.
• When an action is repeated multiple times, such as for each list item, use a tertiary Button.

When should a Button be neutral tertiary?

• When the same Button is repeated, such as for each list item.
• When there’s a group of tertiary Buttons, they all should be neutral.
• When the container background uses the $bg.secondary color.

When should a Button be critical?

A Button should be critical when it triggers an irreversible action. Actions should be reversible whenever possible and not require the critical color.

What to avoid:

Don’t use critical colors for a Move to trash action that implies the possibility of reverting the action.

When should a Button be normal or large?

Use the large size for all primary Buttons. Use the normal size for secondary and tertiary Buttons that are not next to large Buttons.

Position

Where should a Button be positioned in a container?

Considering left-to-right interfaces, follow these recommendations:

• Align Buttons to the right. For example, Buttons in the header of a Card should be vertically-centered and aligned to the right.
• When Buttons are in a horizontal list, order them from tertiary to primary. For example, a secondary Button should be to the left of a primary Button.
• When Buttons are in a vertical list, order them from primary to tertiary. For example, a secondary Button should be below a primary button.
• A secondary Button should be next to either a single primary Button or to one or more tertiary Buttons.
• When a tertiary Button is next to other content, ignore the Button's box to align based on the Button's icon and/or label. Use the bleed prop to implement this alignment.
• When a Button is in a form, align it to the left when it modifies content and to the right when it submits the form.

What to avoid:

• Don't include more than one secondary Button in a list.

Behavior

When to use a disabled Button?

• Use a disabled Button only if, in some condition, it becomes enabled. For example, a Save Button that is only enabled when edits have been made.
• When the reason why an action is disabled might be unclear, leave the action enabled and show a modal explaining it on trigger.

What to avoid:

• Don't display a Tooltip when hovering a disabled Button.

When to use a loading Button?

• Use a loading Button after you trigger an action that usually takes more than a second and less than five seconds to process.
• Actions that take less than a second don't need loading or progress indicators.
• If the action takes more than five seconds to process, open an overlay that includes progress feedback.

When should a Button include a confirmation Modal?

• When the action is irreversible. For example, a Delete action where it isn't possible to restore the item from the trash.
• When the action would take considerable time to undo. For example, a Publish action that takes time and can’t be canceled while in progress.

Content

What should be the label of a Button?

• Reuse existing labels.
• Always include a verb in the infinitive and an object. For example, Create product.
• Use a verb that reflects the exact action that the Button triggers. For example, use a Publish Button instead of a Confirm Button.
• Use sentence case but capitalize proper nouns.

What to avoid:

• Don’t use punctuation.
• Don’t use more than three words.
• Don’t use personal pronouns.

When should a Button include an icon besides a label?

• Always use an icon to the left when the action can be represented by an icon.
• Always use an icon to the left when the actions are in a group.
• Use an external link icon to the right when the Button opens a page in a new tab.

When should a Button have a hidden label and only an icon visible?

• When an icon is easily recognizable by itself. For example, the Close, Forward, and Back icons.
• When the same Button is repeated multiple times on a screen, such as for each list item.

What to avoid:

• Don’t leave a Button without an alternative label. Add it for accessibility in the implementation through the aria-label prop.
• Don’t use an icon-only Button that is not easily understood just because space is constrained.
• Don’t use a Tooltip to display the label.

• What is this?
• Variants
• Button Sizes
• Button With Icon
• Disabled
• Loading