Button

Playground

Textbuttons

"Textbutton" is our name for our standard site button with text on it.

<>
  <TextButton skin="primary">Primary</TextButton>
  <TextButton skin="secondary">Secondary</TextButton>
</>

<button class="textbutton textbutton-skin-primary">Primary</button>
<button class="textbutton textbutton-skin-secondary">Secondary</button>

Textbuttons as links

If clicking on a Textbutton takes the user to a new page, it should be a link instead of a <button> tag:

<TextButton component="a" href="somepage" skin="primary">
  Button as link
</TextButton>

<a class="textbutton textbutton-skin-primary" href="somepage">Button as link</a>

Height

You can make a Textbutton have a "super" (taller) height, or a "mini" (shorter) height.

<>
  <TextButton sizeVariant="super">
    Super button
    <TextButtonSuperBreak />
    with a line break
  </TextButton>
  <TextButton sizeVariant="mini">Mini button</TextButton>
</>

<button class="textbutton textbutton-skin-secondary textbutton-super">
  Super button
  <br class="textbutton-super-break" />
  with a line break
</button>
<button class="textbutton textbutton-skin-secondary textbutton-mini">
  Mini button
</button>

Width

By default, Textbuttons are only as wide as their contents. With the "full-width" option, a Textbutton will expand to fill the width of its container. Here's an example inside a Grid six-column element:

<GridContainer>
  <Row>
    <Column span={6}>
      <TextButton widthVariant="full-width">Full width</TextButton>
    </Column>
  </Row>
</GridContainer>

<button class="textbutton textbutton-skin-secondary textbutton-full-width">
  Full width
</button>

Buttons with Icons

Textbuttons can include icons. Visage itself provides left- and right-pointing arrows as icon choices arrow-l and arrow-r. You can also add a custom icon into a button.

Button with standard icon Button with standard icon at left Custom icon

React (Editable)vanilla

CopyFormat CodeLimited CodeShareCOLUMNReset

CopyFormat CodeLimited CodeShareCOLUMNReset

jsx

<> <TextButton mb="2"> Button with standard icon <TextButtonIcon iconType="arrow-r" /> </TextButton> <TextButton iconPosition="left"> Button with standard icon at left <TextButtonIcon iconType="arrow-l" /> </TextButton> <TextButton> Custom icon <TextButtonIcon iconType="custom"> <BasicResponsiveImage aspectRatio={1} src="https://satyr.dev/32x32/1" /> </TextButtonIcon> </TextButton> </>

<>
  <TextButton mb="2">
    Button with standard icon
    <TextButtonIcon iconType="arrow-r" />
  </TextButton>
  <TextButton iconPosition="left">
    Button with standard icon at left
    <TextButtonIcon iconType="arrow-l" />
  </TextButton>
  <TextButton>
    Custom icon
    <TextButtonIcon iconType="custom">
      <BasicResponsiveImage aspectRatio={1} src="https://satyr.dev/32x32/1" />
    </TextButtonIcon>
  </TextButton>
</>

<button class="textbutton textbutton-skin-secondary textbutton-with-icon">
  Button with standard icon
  <span class="textbutton-icon textbutton-icon-arrow-r"></span>
</button>
<button
  class="
    textbutton
    textbutton-skin-secondary
    textbutton-with-icon
    textbutton-with-icon-left
  "
>
  Button with standard icon
  <span class="textbutton-icon textbutton-icon-arrow-l"></span>
</button>
<button class="textbutton textbutton-skin-secondary textbutton-with-icon">
  Custom icon
  <span class="textbutton-icon textbutton-icon-custom">
    an image goes here
  </span>
</button>

Round buttons

If you want a button that has the TextButton look but (ironically) has no text, you can use a "round textbutton" and put a Control Icon inside it:

<>
  <TextButton buttonShape="round">
    <ControlIcon iconType="arrow-r" />
  </TextButton>
</>

<button class="textbutton textbutton-round textbutton-skin-secondary">
  <span class="control-icon control-icon-arrow-r"></span>
</button>

Disabled buttons

To make a Textbutton disabled, add the HTML disabled property to any Textbutton that is a <button> tag.

If your choice of HTML tag does not support the disabled attribute (e.g. your Textbutton is a <span> tag), add the attribute aria-disabled="true" instead.

<>
  <TextButton disabled="disabled">Disabled button</TextButton>
  <TextButton component="span" aria-disabled="true">
    Disabled button that's a span
  </TextButton>
</>

<button class="textbutton textbutton-skin-secondary" disabled="disabled">
  Disabled button
</button>
<span class="textbutton textbutton-skin-secondary" aria-disabled="true"
  >Disabled button that's a span</span
>

"Design path" button

There is a special version of the Textbutton that is used only for a design path flow. This special variant allows for a second line of text to act as a description.

<GridContainer>
  <Row>
    <Column span={6}>
      <TextButton widthVariant="full-width" specialVariant="design-path">
        <TextButtonIcon iconType="arrow-r" />
        Design Path
        <TextButtonDescription>Here's the description</TextButtonDescription>
      </TextButton>
    </Column>
  </Row>
</GridContainer>

Button Loader

Sometimes when a button is clicked, the user needs to wait for a little bit while things are processing. In order to indicate that some sort of processing is taking place, you can render a Preloader inside of a TextButton.

When a Preloader is rendered inside of a TextButton, it gets a new look that's specifically designed for buttons.

<TextButton>
  <BasicPreloader />
  Reload
</TextButton>

() => {
  const [isPlacingOrder, setIsPlacingOrder] = React.useState(false)
  return (
    <TextButton
      onClick={() => {
        setIsPlacingOrder(true)
        // reset the button after a few seconds for demo purposes
        setTimeout(() => {
          setIsPlacingOrder(false)
        }, 2000)
      }}
    >
      {isPlacingOrder && <BasicPreloader />}
      {isPlacingOrder ? 'Placing order' : 'Place order'}
    </TextButton>
  )
}

Do

• Use a primary button to show an important CTA for users.

• Use primary and secondary buttons side by side when there are multiple CTAs. The more important CTA should be primary, to create information hierarchy.

• Align buttons accordingly with the content grouping for visual consistency. For example, left-aligned typography includes a left-aligned button.

• Align buttons based on where they appear on a page, dialog, form, or panel.

• Keep button text clear and short, with directive language to signal what will happen next. Try to lead with a verb.

Don't

• Use too many buttons on a page.

• Alter the button shape, height or width. Button size variations are available for different use cases.

• Use lengthy text inside a button.

• Use buttons for navigation. Use links instead.

Designer Guidelines

• A "Primary" button is the call to action (CTA) for the primary action or outcome on a webpage. Only one "Primary" CTA should be shown at once, unless the decision choices are of equal weight and/or value.

• A "Secondary" button is for secondary actions. Numerous "Secondary" buttons can be shown at once.

• The "Super" option should only be used when the text is long enough to warrant wrapping onto two lines.

• The "Disabled" option is used when an option or action is unavailable.

• Use clear, concise, descriptive copy of the action being performed on the button.

• Place buttons in flow near relevant content, with negative space to call the maximum amount of attention to the action.

• Ensure buttons have appropriate contrast when placed on busy backgrounds.

• For Textbuttons with custom icons, the icons should be inline (as <img> tags). Images should be square, and at least 36px by 36px. The icon will stretch to fill the available space inside the button, so if you want the icon to appear smaller, you will want to include whitespace in the image itself, around the visible part of the icon.

Developer Guidelines

• Buttons will grow wide enough to accommodate their text. If there is not enough room for the button to grow, a button will truncate the text with ellipses. Button text will not normally line-wrap onto two lines.

• Ideally, a textbutton should be a link (an <a> tag) if clicking it takes you to another page. In cases where you have to place a textbutton inside a link, the link may apply an underline to the text inside the button. In this case, use class link-skin-unstyled on the link to remove the underline from the link.

• "Super" buttons can wrap onto two lines a button lacks enough space to display the text on one line. However, they will not naturally wrap onto two lines if there is enough space to display the text on one line. If two lines is desired, you will likely need to force a line break into the button text.

• "Super" buttons that are <a> or <span> tags should not put any additional tags inside the button other than a <br> tag or an icon. Super buttons with these tags use flex layout, and any internal tags will be treated as flexbox children, which can affect the button's layout.

• While the "textbutton with icon" feature will work on a <button> tag, it can't be used on an <input> tag.

Accessibility Guidelines

• Use the <button> tag for textbuttons that interact with the page, the <a> tag for "buttons" that are hyperlinks to a new page, and <span> tags only when the previous two tags can't be used for some reason.

• Buttons that are <span> tags also need to make them usable with a keyboard and/or screen reader. They also need the attribute role="button" to mark them functionally as buttons.

Clear Selection buttons

Clear Selection buttons are for where the user has made selections, and those selections can be cancelled. The button shows a current selection, with an "X" icon indicating that the user can click the button to cancel that selection.

<ClearSelectionButtons>
  <TextButton skin="clear-selection">
    <VisuallyHidden>Remove </VisuallyHidden>
    Selection 1
  </TextButton>
  <TextButton skin="clear-selection">
    <VisuallyHidden>Remove </VisuallyHidden>
    Selection 2
  </TextButton>
  <TextButton skin="clear-selection">
    <VisuallyHidden>Remove </VisuallyHidden>
    Selection 3
  </TextButton>
  <ClearAllButton component="button">
    Clear All
    <VisuallyHidden> Selections</VisuallyHidden>
  </ClearAllButton>
</ClearSelectionButtons>

<div class="clear-selection-buttons">
  <button class="stylized-button-skin-clear-selection">Selection 1</button>
  <button class="stylized-button-skin-clear-selection">Selection 2</button>
  <button class="stylized-button-skin-clear-selection">Selection 3</button>
  <button class="link">Clear All</button>
</div>

Clear Selections buttons can also use the size variant option to be "mini" height.

<ClearSelectionButtons>
  <TextButton skin="clear-selection" sizeVariant="mini">
    <VisuallyHidden>Remove </VisuallyHidden>
    Selection 1
  </TextButton>
  <TextButton skin="clear-selection" sizeVariant="mini">
    <VisuallyHidden>Remove </VisuallyHidden>
    Selection 2
  </TextButton>
  <TextButton skin="clear-selection" sizeVariant="mini">
    <VisuallyHidden>Remove </VisuallyHidden>
    Selection 3
  </TextButton>
  <ClearAllButton component="button" sizeVariant="mini">
    Clear All
    <VisuallyHidden> Selections</VisuallyHidden>
  </ClearAllButton>
</ClearSelectionButtons>

Other buttons

We have other buttons that semantically are buttons (and thus use the <button> tag), but don't look like buttons.

"Link" and "unstyled" buttons

If something looks like a "link", but performs an action on the current page instead of taking the user to a new location, then semantically it's a <button> and not a link, so it should use a <button>.

If something looks like a "link", but performs an action on the current page instead of taking the user to a new location, then semantically it's a <button> and not a link, so it should use a <button>.

<Link component="button" onClick={() => alert('Clicked a button!')}>
  Perform a non-navigation action
</Link>

<button class="link">Perform a non-navigation action</button>
<button class="link-skin-cta">This button looks like a CTA link</button>

Designer Guidelines

• CTA links should not be used for inline links, and should only be used in specific locations such as Standard Heroes and Standard Tiles.

Developer Guidelines

• "Link" buttons can also use the "link-with-icon" feature, and can have a Control Icon inside them.

"Unstyled" buttons

If a button should have no styling at all, you can use an "Unstyled" button:

I'm an Unstyled button

Note that "unstyled" buttons provide no affordance on touch devices and little affordance on desktops, so should only be used to wrap a component that provides its own affordance.

<TextButton skin="unstyled">Button Text Goes Here</TextButton>

<button class="stylized-button-skin-unstyled">Button Text Goes Here</button>

Designer Guidelines

• "Unstyled" buttons provide no affordance, so their contents must provide affordance instead.

Components