button

26 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Button component primary purpose

Buttons are used primarily for actions such as 'Add', 'Close', 'Cancel', or 'Save'. Plain buttons, which look similar to links, are used for less important or less commonly used actions, such as 'view shipping settings'.

Button variants and use cases

Button variants include: Default (used most in the interface, only use another style if a button requires more or less visual weight); Plain (use for less important or less commonly used actions since they're less prominent, used as actions in cards); Tertiary (use for tertiary actions, can be paired with any other button style); Plain critical (use for actions that will delete merchant data or be otherwise difficult to recover from); Primary (use to highlight the most important actions, don't use more than one primary button in a section or screen); Primary critical (use when the action will delete merchant data or be otherwise difficult to recover from, should trigger a confirmation dialog); Large (use for the main call to action in empty states or with large illustrations); Full-width (use for buttons in narrow columns or to create equal width button sets, should rarely exceed 320 px wide); Text-aligned (use for plain or monochrome buttons with potentially long length); Pressed (used as a toggle for other parts of the user interface); Plain disclosure (indicate that more content can be disclosed on click); Right-aligned disclosure (when working with fullWidth + textAlign='left', disclosure aligns to the far right); Select disclosure (indicate that multiple options are available, similar to HTML select element); Split (use when there is only one primary action but other related actions can be taken); Disabled state (for actions that aren't currently available); Loading state (use when a button has been pressed and the action is in progress); With icon (include an icon with any button variant and tone); Icon only (use with an accessibility label to have an icon-only button).

Button best practices

Buttons should: (1) Be clearly and accurately labeled. (2) Lead with a strong, actionable verb. (3) Use established button colors appropriately - only use a red button for an action that's difficult or impossible to undo. (4) Prioritize the most important actions, as too many calls to action can cause confusion and make merchants unsure of what to do next. (5) Be positioned in consistent locations in the interface.

Button content guidelines - verbs and words

Buttons should use universally understood iconography instead of words wherever possible. Verbs like 'View', 'Go', or 'Read' are often unnecessary since the button itself already conveys these actions. Button text should use sentence case (first word capitalized, rest lowercase unless a proper noun). No articles ('a', 'an', 'the') should be used. No punctuation should be used.

Button content examples - do and don't

Do use: 'Save', 'Edit', 'Add tags', 'Buy new domain', 'Add menu item'. Don't use: 'Save product', 'Edit collection', 'Add tag(s)', 'Buy New Domain', 'Add a menu item'.

Button accessibility - state management

Buttons can have different states that are visually and programmatically conveyed to merchants. Use the ariaControls prop to add an aria-controls attribute to point to the unique id of content that the button manages. Use the ariaExpanded prop to add the aria-expanded attribute if a button expands or collapses adjacent content, setting the value to true (expanded) or false (collapsed). Use the disabled prop to set the disabled state of the button. Use the pressed prop to add an aria-pressed attribute to the button.

Button accessibility - navigation

Merchants generally expect buttons to submit data or take action, and for links to navigate. If navigation is required for the button component, use the url prop. The control will output an anchor styled as a button, instead of a button in HTML, to help convey this difference.

Button accessibility - labeling with accessibilityLabel

Use the accessibilityLabel prop to add an aria-label attribute to the button. Use accessibilityLabel for a button if: (1) The button's visible text doesn't adequately convey the purpose to non-visual merchants, or (2) The button has no text and relies on an icon alone. To support merchants using speech activation software and sighted screen reader users, ensure the aria-label text includes any button text that's visible. When possible, give the button visible text that clearly conveys its purpose. When no additional content is needed, duplicating the button text with accessibilityLabel isn't necessary.

Button accessibility - labeling examples

Do use: '<Button>Edit shipping address</Button>' for clear visible text, or '<Heading>Shipping address</Heading><Button accessibilityLabel="Edit shipping address">Edit</Button>' when abbreviated text needs context. Don't use: '<Button accessibilityLabel="Change your shipping address">Edit</Button>' (mismatch where aria-label adds new information not in visible text), or '<Button accessibilityLabel="Edit">Edit</Button>' (unnecessary duplication when visible text is already clear).

Button accessibility - external links

When using the button component to create a link to an external resource: (1) Use the external prop to make the link open in a new tab or window. (2) Use the icon prop to add the external icon to the button. (3) Use the accessibilityLabel prop to include the warning about opening a new tab in the button text for non-visual screen reader users.

Button accessibility - external link example

Do use: '<Button accessibilityLabel="Terms and conditions (opens a new window)" icon={ExternalIcon} url="http://example.com" external>Terms and conditions</Button>'. Don't use: '<Button url="http://example.com" external>Terms and conditions</Button>' or the same without the external prop.

Button keyboard support

Buttons use browser defaults for keyboard interactions. Give buttons keyboard focus with the Tab key (or Shift+Tab when tabbing backwards). Activate buttons with the Enter/Return key or the Space key.

Button custom key events

Use the onKeyDown, onKeyPress, and onKeyUp props to create custom events for buttons. With these props, you can use buttons to create complex, custom interactions like drag-and-drop interfaces. Since these props introduce non-standard features to buttons, make sure to include accessible instructions so that merchants can understand how to use these features.

Button web component

The Button component is available as a web component named 's-button'. Documentation for the web component is available at https://shopify.dev/docs/api/app-home/polaris-web-components/button.

Button labels should be clear and predictable

Button labels should be clear and predictable so merchants can anticipate what will happen when they click. Never deceive merchants by mislabeling a button. Good examples: 'Create order', 'Buy shipping label'. Bad examples: 'New order', 'Buy'.

Button labels should be action-led

Button labels should always lead with a strong verb that encourages action. Use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK. Good examples: 'Activate Apple Pay', 'View shipping settings'. Bad examples: 'Try Apple Pay', 'View your settings'.

Button labels should be scannable

Button labels should avoid unnecessary words and articles such as the, an, or a. Good example: 'Add menu item'. Bad example: 'Add a menu item'.

Callout card button should be clear and predictable

Buttons should be clear and predictable so merchants can anticipate what will happen when they click. Never deceive merchants by mislabeling a button. For example, write 'Buy shipping label' instead of 'Buy'.

Callout card button should be action-led

Buttons should always lead with a strong verb that encourages action. Use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK. For example, write 'View shipping settings' instead of 'View your settings'.

Callout card button should be scannable

Avoid unnecessary words and articles such as the, an, or a in button labels. For example, write 'Add menu item' instead of 'Add a menu item'.

Form submit button rules

Forms can have only one submit button and it must be at the end of the form. By default, buttons added to the form are given a type attribute set to button to avoid conflicts. To make a button the submit button instead (type="submit"), set the submit prop on the button.

Button sizing depends on context

Buttons are shaped elements whose sizing depends on context. Standalone or grouped, buttons have a default size that is widely used in the admin. Because buttons often pull the most attention to a primary action, their size has been adjusted so as to not overwhelm the visual balance of the admin.

Button boolean props consolidated to variant and tone in v12

Button component has consolidated boolean props to use variant and tone props. The deprecated props are: connectedDisclosure, outline, destructive, primary, primarySuccess, plain, and monochrome. These map to various combinations of variant and tone.

Button variant and tone consolidation mappings

Button v12 mappings: plain=true becomes variant="plain"; primary=true becomes variant="primary"; primary=true + plain=true becomes variant="tertiary"; primary=true + destructive=true becomes variant="primary" + tone="critical"; monochrome=true + plain=true becomes variant="monochromePlain" (deprecated); destructive=true becomes variant="primary" + tone="critical"; primarySuccess=true becomes variant="primary" + tone="success"; destructive=true + outline=true becomes tone="critical"; destructive=true + plain=true becomes variant="plain" + tone="critical"; monochrome=true becomes no props (default); outline=true becomes no props (default).

Button connectedDisclosure prop replacement pattern

The Button connectedDisclosure prop should be replaced with ButtonGroup variant="segmented". The old pattern <Button connectedDisclosure={{icon: ChevronDownMinor}}>Save</Button> becomes <ButtonGroup variant="segmented"><Button>Save</Button><Popover activator={<Button icon={ChevronDownMinor} />}/></ButtonGroup>.

Button height change: use large size variant for inputs

Default buttons have decreased in height in v12 and no longer match the height of TextField and Select inputs. To match button height to input fields, use the large size variant: <Button size="large" />.

Give your agent this brain