{"componentChunkName":"component---src-pages-components-button-usage-mdx","path":"/components/button/usage/","result":{"pageContext":{"isCreatedByStatefulCreatePages":true,"frontmatter":{"title":"Button","description":"Buttons are used to initialize an action. Button labels express what action will occur when the user interacts with it.","tabs":["Code","Usage","Style"]},"relativePagePath":"/components/button/usage.mdx","titleType":"prepend","MdxNode":{"id":"87f09e59-19cf-54bc-a5fa-913188c7e843","children":[],"parent":"136b9afa-ad97-598e-afb8-0fb312e1a644","internal":{"content":"---\ntitle: Button\ndescription: Buttons are used to initialize an action. Button labels express what action will occur when the user interacts with it.\ntabs: ['Code', 'Usage', 'Style']\n---\n\n\n\nGeneral guidance\nButton order\nButton alignment\nLabels\nIcon usage\nDanger button usage\nVariations\nReferences\n\n\n\n## General guidance\n\n**Buttons are used to initialize an action.** Button labels express what action will occur when the user interacts with it.\n\n**Buttons are used primarily for actions.** Examples include Add, Save, Delete, and Sign up. Each page should have one primary button, and a **Return** or **Enter** keyboard event should trigger it. Any remaining calls-to-action should be represented as secondary buttons.\n\n**Do not use buttons as navigational elements.** Instead, use [links](/components/link/code) when the desired action is to take the user to a new page.\n\n**Primary buttons always appear to the right.** Secondary buttons appear to the left of the primary button.\n\n## Button order\n\nWhen using multiple buttons, the primary button appears to the right and any secondary buttons appear to the left. Research has shown that performance differences between secondary and primary button placement are negligible, however [maintaining consistency](https://www.nngroup.com/articles/ok-cancel-or-cancel-ok/) throughout a product, offering, or platform is crucial. The Secondary / Primary button order (secondary to the left and primary to the right) is therefore our required guidance and should be followed at all times.\n\n\n\n\n\n\nSecondary / Primary button order in a modal\n\n\n
\n\n## Button alignment\n\nButton alignment depends on where the buttons appear.\n\n- Use full-bleed or full-justified buttons for modals and side panels.\n- Use left-justified buttons for forms on their own page (not in a modal or side panel).\n- Use right-justified buttons if the primary response advances the user through a multi-step configuration such as a wizard.\n\n### Modal button alignment\n\nSingle buttons or button groups in modals use full-bleed, full-width buttons. Single buttons span the full width of the modal.\n\nFull-width buttons provide significant advantages in time-to-target evaluations using [Fitts’ Law](https://www.interaction-design.org/literature/book/the-glossary-of-human-computer-interaction/fitts-s-law), and are increasingly common in other contexts users are likely to encounter.\n\n\n\n\n\n\nSingle primary button in a modal\n\n\n
\n\n\n\n\n\n\nSecondary / Primary button pair in a modal\n\n\n
\n\nIf there is a third action, place this within the modal itself as a link, rather than alongside the Secondary / Primary buttons.\n\n\n\n\n\n\n\n Secondary / Primary button pair with a tertiary action in a modal\n\n\n\n
\n\nUse this same layout for buttons in side panels. Use full-width single buttons or full-width Secondary / Primary button pairs. If there is a third action, considering placing it within the side panel itself, rather than as part of the button group.\n\nSide panel buttons should be visible without scrolling. They should be visible if they’re at the top, the bottom (without scrolling), or sticky and at the bottom of the view if the content is longer than the viewport.\n\n### Non-modal forms\n\nOn non-modal or in-page forms, align single buttons or Secondary / Primary button groups to the left. Buttons should align with the form controls regardless of the user‘s window width.\n\n\n\n\n\n\nSingle button alignment in forms\n\n\n
\n\n\n\n\n\n\nSecondary / Primary button alignment in forms\n\n\n
\n\n### Multi-step forms\n\nWhen the primary action implies a navigation step forward, as in a wizard, align single buttons or Secondary/Primary button groups to the right. This position conveys the “next step” intention.\n\n\n\n\n\n\nSingle button alignment in a wizard\n\n\n
\n\n\n\n\n\n\nSecondary / Primary button pair alignment in a wizard\n\n\n
\n\n## Labels\n\nButton labels should clearly indicate the action of the button. Use active verbs, such as **Add** or **Delete**. Use sentence-style capitalization (only the first word in a phrase and any proper nouns capitalized) and no more than three words for button labels.\n\nFor sets of buttons, use specific labels, such as **Save** or **Discard**, instead of using **OK** and **Cancel**. This is particularly helpful when the user is confirming an action.\n\nFor consistency, see [labels and idioms](/guidelines/content/glossary) for the approved list of action labels.\n\n## Icon usage\n\n- Use glyphs (16px) within buttons.\n- Glyphs are distinguished by their solid shape and knocked-out details.\n- Glyphs should always appear to the right of the text.\n- Glyphs used in buttons must be directly related to the action that the user is taking.\n- Glyphs must be the same color value as the text within a button.\n- Ghost buttons require a glyph icon.\n\n\n\n\n\n\nGlyph usage in buttons\n\n\n
\n\n## Danger button usage\n\nDanger buttons have a different visual style to inform users of potentially destructive actions they are about to take. If using the danger button as a standalone, we recommend styling it as a **secondary button**. Within a set, the danger button should be styled as a **primary button.**\n\n\n\n\n\n\nDanger button set\n\n\n
\n\n## Variations\n\n| Button type | Purpose |\n| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| _Primary_ | For the principal call to action on the page. |\n| _Secondary_ | For secondary actions on each page. |\n| _Button with icon_ | When words are not enough, icons can be used in buttons to better communicate what the button does. Icons are always paired with text. |\n| _Disabled button_ | Use when the user cannot proceed until an input is collected. |\n| _Set of buttons_ | When an action required by the user has more than one option, always use a a negative action button (secondary) paired with a positive action button (primary) in that order. Negative action buttons will be on the left; positive action buttons on the right. When these two types of buttons are paired in the correct order, they will automatically space themselves apart. |\n| _Small button_ | Use when there is not enough vertical space for a regular sized button. |\n| _Ghost button_ | When an action does not require primary dominance on the page. |\n| _Danger button_ | When an action has potentially destructive effects on the user‘s data (delete, remove, etc). |\n\n## References\n\n- Jakob Nielsen, [_OK-Cancel or Cancel-OK? The Trouble With Buttons_](https://www.nngroup.com/articles/ok-cancel-or-cancel-ok/) (2008)\n- The Interaction Design Foundation, [_The Glossary of Human Computer Interaction, Chapter 37_](https://www.interaction-design.org/literature/book/the-glossary-of-human-computer-interaction/fitts-s-law)\n","type":"Mdx","contentDigest":"f6d448c323cb7f888e5d7e5d9c68533c","counter":1485,"owner":"gatsby-plugin-mdx"},"frontmatter":{"title":"Button","description":"Buttons are used to initialize an action. Button labels express what action will occur when the user interacts with it.","tabs":["Code","Usage","Style"]},"exports":{},"rawBody":"---\ntitle: Button\ndescription: Buttons are used to initialize an action. Button labels express what action will occur when the user interacts with it.\ntabs: ['Code', 'Usage', 'Style']\n---\n\n\n\nGeneral guidance\nButton order\nButton alignment\nLabels\nIcon usage\nDanger button usage\nVariations\nReferences\n\n\n\n## General guidance\n\n**Buttons are used to initialize an action.** Button labels express what action will occur when the user interacts with it.\n\n**Buttons are used primarily for actions.** Examples include Add, Save, Delete, and Sign up. Each page should have one primary button, and a **Return** or **Enter** keyboard event should trigger it. Any remaining calls-to-action should be represented as secondary buttons.\n\n**Do not use buttons as navigational elements.** Instead, use [links](/components/link/code) when the desired action is to take the user to a new page.\n\n**Primary buttons always appear to the right.** Secondary buttons appear to the left of the primary button.\n\n## Button order\n\nWhen using multiple buttons, the primary button appears to the right and any secondary buttons appear to the left. Research has shown that performance differences between secondary and primary button placement are negligible, however [maintaining consistency](https://www.nngroup.com/articles/ok-cancel-or-cancel-ok/) throughout a product, offering, or platform is crucial. The Secondary / Primary button order (secondary to the left and primary to the right) is therefore our required guidance and should be followed at all times.\n\n\n\n\n\n\nSecondary / Primary button order in a modal\n\n\n
\n\n## Button alignment\n\nButton alignment depends on where the buttons appear.\n\n- Use full-bleed or full-justified buttons for modals and side panels.\n- Use left-justified buttons for forms on their own page (not in a modal or side panel).\n- Use right-justified buttons if the primary response advances the user through a multi-step configuration such as a wizard.\n\n### Modal button alignment\n\nSingle buttons or button groups in modals use full-bleed, full-width buttons. Single buttons span the full width of the modal.\n\nFull-width buttons provide significant advantages in time-to-target evaluations using [Fitts’ Law](https://www.interaction-design.org/literature/book/the-glossary-of-human-computer-interaction/fitts-s-law), and are increasingly common in other contexts users are likely to encounter.\n\n\n\n\n\n\nSingle primary button in a modal\n\n\n
\n\n\n\n\n\n\nSecondary / Primary button pair in a modal\n\n\n
\n\nIf there is a third action, place this within the modal itself as a link, rather than alongside the Secondary / Primary buttons.\n\n\n\n\n\n\n\n Secondary / Primary button pair with a tertiary action in a modal\n\n\n\n
\n\nUse this same layout for buttons in side panels. Use full-width single buttons or full-width Secondary / Primary button pairs. If there is a third action, considering placing it within the side panel itself, rather than as part of the button group.\n\nSide panel buttons should be visible without scrolling. They should be visible if they’re at the top, the bottom (without scrolling), or sticky and at the bottom of the view if the content is longer than the viewport.\n\n### Non-modal forms\n\nOn non-modal or in-page forms, align single buttons or Secondary / Primary button groups to the left. Buttons should align with the form controls regardless of the user‘s window width.\n\n\n\n\n\n\nSingle button alignment in forms\n\n\n
\n\n\n\n\n\n\nSecondary / Primary button alignment in forms\n\n\n
\n\n### Multi-step forms\n\nWhen the primary action implies a navigation step forward, as in a wizard, align single buttons or Secondary/Primary button groups to the right. This position conveys the “next step” intention.\n\n\n\n\n\n\nSingle button alignment in a wizard\n\n\n
\n\n\n\n\n\n\nSecondary / Primary button pair alignment in a wizard\n\n\n
\n\n## Labels\n\nButton labels should clearly indicate the action of the button. Use active verbs, such as **Add** or **Delete**. Use sentence-style capitalization (only the first word in a phrase and any proper nouns capitalized) and no more than three words for button labels.\n\nFor sets of buttons, use specific labels, such as **Save** or **Discard**, instead of using **OK** and **Cancel**. This is particularly helpful when the user is confirming an action.\n\nFor consistency, see [labels and idioms](/guidelines/content/glossary) for the approved list of action labels.\n\n## Icon usage\n\n- Use glyphs (16px) within buttons.\n- Glyphs are distinguished by their solid shape and knocked-out details.\n- Glyphs should always appear to the right of the text.\n- Glyphs used in buttons must be directly related to the action that the user is taking.\n- Glyphs must be the same color value as the text within a button.\n- Ghost buttons require a glyph icon.\n\n\n\n\n\n\nGlyph usage in buttons\n\n\n
\n\n## Danger button usage\n\nDanger buttons have a different visual style to inform users of potentially destructive actions they are about to take. If using the danger button as a standalone, we recommend styling it as a **secondary button**. Within a set, the danger button should be styled as a **primary button.**\n\n\n\n\n\n\nDanger button set\n\n\n
\n\n## Variations\n\n| Button type | Purpose |\n| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| _Primary_ | For the principal call to action on the page. |\n| _Secondary_ | For secondary actions on each page. |\n| _Button with icon_ | When words are not enough, icons can be used in buttons to better communicate what the button does. Icons are always paired with text. |\n| _Disabled button_ | Use when the user cannot proceed until an input is collected. |\n| _Set of buttons_ | When an action required by the user has more than one option, always use a a negative action button (secondary) paired with a positive action button (primary) in that order. Negative action buttons will be on the left; positive action buttons on the right. When these two types of buttons are paired in the correct order, they will automatically space themselves apart. |\n| _Small button_ | Use when there is not enough vertical space for a regular sized button. |\n| _Ghost button_ | When an action does not require primary dominance on the page. |\n| _Danger button_ | When an action has potentially destructive effects on the user‘s data (delete, remove, etc). |\n\n## References\n\n- Jakob Nielsen, [_OK-Cancel or Cancel-OK? The Trouble With Buttons_](https://www.nngroup.com/articles/ok-cancel-or-cancel-ok/) (2008)\n- The Interaction Design Foundation, [_The Glossary of Human Computer Interaction, Chapter 37_](https://www.interaction-design.org/literature/book/the-glossary-of-human-computer-interaction/fitts-s-law)\n","fileAbsolutePath":"/zeit/3ed0734e/src/pages/components/button/usage.mdx"}}}}