Button

Used to trigger an in-page action such as submitting a form or showing/hiding an interface component.

styleKeys: buttonstyleKeys: spinner

Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.

UsageGuidelinesAPI

Use Button...

To trigger an in-page action such as submitting a form or showing/hiding an interface component.

Don't use Button...

To link to another page. Use Link instead, or render the Button as a link.

ReactVanilla

<Button>Button</Button>

<Button>Button</Button>

<button class="swan-button">Button</button>

<button class="swan-button">Button</button>

Skin

Use skin to choose the styling of Button based on the use case. Refer to guidelines on which skin to use.

ReactVanilla

<FlexBox flexWrap="wrap" gap="between-actions">
  <Button skin="primary">Primary</Button>
  <Button skin="secondary">Secondary</Button>
  <Button skin="tertiary">Tertiary</Button>
  <Button skin="destructive-primary">Destructive Primary</Button>
  <Button skin="destructive-secondary">Destructive Secondary</Button>
  <Button skin="destructive-tertiary">Destructive Tertiary</Button>
</FlexBox>

<FlexBox flexWrap="wrap" gap="between-actions">
  <Button skin="primary">Primary</Button>
  <Button skin="secondary">Secondary</Button>
  <Button skin="tertiary">Tertiary</Button>
  <Button skin="destructive-primary">Destructive Primary</Button>
  <Button skin="destructive-secondary">Destructive Secondary</Button>
  <Button skin="destructive-tertiary">Destructive Tertiary</Button>
</FlexBox>

<button class="swan-button swan-button-skin-primary">Primary</button>
<button class="swan-button swan-button-skin-secondary">Secondary</button>
<button class="swan-button swan-button-skin-tertiary">Tertiary</button>
<button class="swan-button swan-button-skin-destructive-primary">
  Destructive Primary
</button>
<button class="swan-button swan-button-skin-destructive-secondary">
  Destructive Secondary
</button>
<button class="swan-button swan-button-skin-destructive-tertiary">
  Destructive Tertiary
</button>

<button class="swan-button swan-button-skin-primary">Primary</button>
<button class="swan-button swan-button-skin-secondary">Secondary</button>
<button class="swan-button swan-button-skin-tertiary">Tertiary</button>
<button class="swan-button swan-button-skin-destructive-primary">
  Destructive Primary
</button>
<button class="swan-button swan-button-skin-destructive-secondary">
  Destructive Secondary
</button>
<button class="swan-button swan-button-skin-destructive-tertiary">
  Destructive Tertiary
</button>

Size

size is deprecated in SWAN v3.3

The component now automatically handles sizing based on the selected mode(standardMode/compactMode). Please update your implementation to rely on the new mode-based sizing.

Use size="mini" to reduce the size of a Button.

ReactVanilla

<Button size="mini">Mini</Button>

<Button size="mini">Mini</Button>

<button type="button" class="swan-button swan-button-mini">Mini</button>

<button type="button" class="swan-button swan-button-mini">Mini</button>

Width

Use width="full-width" to grow a Button to fill its container.

ReactVanilla

<Button width="full-width">Full width</Button>

<Button width="full-width">Full width</Button>

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

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

Disabled

Use disabled when a Button’s action is unavailable. Refer to guidelines.

Use the attribute aria-disabled="true" if the HTML tag does not support the disabled attribute. Notably this applies to span.

ReactVanilla

<Button disabled>Disabled button</Button>

<Button disabled>Disabled button</Button>

<button
  disabled=""
  type="button"
  class="swan-button swan-button-skin-secondary"
>
  Disabled button
</button>

<button
  disabled=""
  type="button"
  class="swan-button swan-button-skin-secondary"
>
  Disabled button
</button>

Icons

An Icon can be placed inside Buttons. Use buttonShape="round" for icon only buttons. Use objectFit to accommodate different sized custom icons.

If the Button has no text you must include accessible text via aria-label on Button or with an alt attribute on Icon.

ReactVanilla

<FlexBox flexWrap="wrap" gap="between-actions">
  <Button>
    Icon
    <Icon iconType="image" />
  </Button>
  <Button iconPosition="left">
    Icon position left
    <Icon iconType="image" />
  </Button>
  <Button buttonShape="round">
    <Icon alt="image" iconType="image" />
  </Button>
  <Button>
    <Icon src="https://placehold.co/32x32/3f51b5/ffffff?text=X" />
    Custom icon
  </Button>
</FlexBox>

<FlexBox flexWrap="wrap" gap="between-actions">
  <Button>
    Icon
    <Icon iconType="image" />
  </Button>
  <Button iconPosition="left">
    Icon position left
    <Icon iconType="image" />
  </Button>
  <Button buttonShape="round">
    <Icon alt="image" iconType="image" />
  </Button>
  <Button>
    <Icon src="https://placehold.co/32x32/3f51b5/ffffff?text=X" />
    Custom icon
  </Button>
</FlexBox>

<div>
  <button type="button" class="swan-button swan-button-skin-secondary">
    Icon
    <img
      src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
      alt=""
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-image"
      style='mask-image: url("https://swan.prod.merch.vpsvc.com/v3/icons/image.9450c651fb1053109493a08d371842b0.svg");'
    /></button
  ><button
    type="button"
    class="swan-button swan-button-skin-secondary swan-button-with-icon-left swan-ml-between-actions"
  >
    Icon position left
    <img
      src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
      alt=""
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-image"
      style='mask-image: url("https://swan.prod.merch.vpsvc.com/v3/icons/image.9450c651fb1053109493a08d371842b0.svg");'
    /></button
  ><button
    type="button"
    class="swan-button swan-button-skin-secondary swan-button-round swan-ml-between-actions"
  >
    <img
      alt="image"
      src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-image"
      style='mask-image: url("https://swan.prod.merch.vpsvc.com/v3/icons/image.9450c651fb1053109493a08d371842b0.svg");'
    /></button
  ><button
    type="button"
    class="swan-button swan-button-skin-secondary swan-ml-between-actions"
  >
    <img
      src="https://placehold.co/32/3f51b5/ffffff?text=X"
      alt=""
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-custom"
    />Custom icon
  </button>
</div>

<div>
  <button type="button" class="swan-button swan-button-skin-secondary">
    Icon
    <img
      src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
      alt=""
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-image"
      style='mask-image: url("https://swan.prod.merch.vpsvc.com/v3/icons/image.9450c651fb1053109493a08d371842b0.svg");'
    /></button
  ><button
    type="button"
    class="swan-button swan-button-skin-secondary swan-button-with-icon-left swan-ml-between-actions"
  >
    Icon position left
    <img
      src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
      alt=""
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-image"
      style='mask-image: url("https://swan.prod.merch.vpsvc.com/v3/icons/image.9450c651fb1053109493a08d371842b0.svg");'
    /></button
  ><button
    type="button"
    class="swan-button swan-button-skin-secondary swan-button-round swan-ml-between-actions"
  >
    <img
      alt="image"
      src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-type-image"
      style='mask-image: url("https://swan.prod.merch.vpsvc.com/v3/icons/image.9450c651fb1053109493a08d371842b0.svg");'
    /></button
  ><button
    type="button"
    class="swan-button swan-button-skin-secondary swan-ml-between-actions"
  >
    <img
      src="https://placehold.co/32/3f51b5/ffffff?text=X"
      alt=""
      class="swan-icon swan-icon-mask swan-icon-skin-standard swan-icon-custom"
    />Custom icon
  </button>
</div>

Loading

Use loading to indicate that an action is in progress. The Button will render a [Spinner] to visually indicate the loading state.

For assistive technologies, the visual updates must be accompanied by an ARIA live region on your page (not as a descendant of Button) to announce changes even when the Button is not in focus.

Do not render the live region conditionally as it can lead to announcement issues - instead render the text inside the live region conditionally. An example can be seen below:

ReactVanilla

<Button loading>Submit</Button>

<Button loading>Submit</Button>

<button
  aria-disabled="true"
  type="button"
  class="swan-button swan-button-skin-secondary swan-button-loading"
>
  Submit<span aria-hidden="true" class="swan-spinner"
    ><span class="swan-spinner-animation"
      ><span class="swan-spinner-animation-inner"></span></span
    ><span class="swan-spinner-text"></span
  ></span>
</button>

<button
  aria-disabled="true"
  type="button"
  class="swan-button swan-button-skin-secondary swan-button-loading"
>
  Submit<span aria-hidden="true" class="swan-spinner"
    ><span class="swan-spinner-animation"
      ><span class="swan-spinner-animation-inner"></span></span
    ><span class="swan-spinner-text"></span
  ></span>
</button>

() => {
  const [loadingText, setLoadingText] = React.useState('')

  const updateText = () => {
    setLoadingText('Processing')
    setTimeout(() => {
      setLoadingText('Submitted')
    }, 1000)
    setTimeout(() => {
      setLoadingText('')
    }, 2000)
  }

  return (
    <>
      <VisuallyHidden role="status" aria-atomic="true" aria-live="polite">
        {loadingText}
      </VisuallyHidden>
      <Button
        loading={!!loadingText}
        type="submit"
        skin="primary"
        onClick={updateText}
      >
        Submit form
      </Button>
    </>
  )
}

() => {
  const [loadingText, setLoadingText] = React.useState('')

  const updateText = () => {
    setLoadingText('Processing')
    setTimeout(() => {
      setLoadingText('Submitted')
    }, 1000)
    setTimeout(() => {
      setLoadingText('')
    }, 2000)
  }

  return (
    <>
      <VisuallyHidden role="status" aria-atomic="true" aria-live="polite">
        {loadingText}
      </VisuallyHidden>
      <Button
        loading={!!loadingText}
        type="submit"
        skin="primary"
        onClick={updateText}
      >
        Submit form
      </Button>
    </>
  )
}

Design Path

Use specialVariant="design-path" for Buttons in the design path flow that require a second line for a description.

ReactVanilla

<Button specialVariant="design-path">
  <Icon iconType="arrowRight" size="20p" />
  Design Path
  <ButtonDescription>Short description</ButtonDescription>
</Button>

<Button specialVariant="design-path">
  <Icon iconType="arrowRight" size="20p" />
  Design Path
  <ButtonDescription>Short description</ButtonDescription>
</Button>

<button
  type="button"
  class="swan-button swan-button-skin-secondary swan-button-with-icon-right swan-button-design-path"
>
  <img
    src="https://swan.prod.merch.vpsvc.com/v2/icons/arrow_right.b75db7a964c0e26c4d1da0075e0a7ad6.svg"
    alt=""
    class="swan-icon swan-icon-size-20p swan-icon-skin-standard swan-icon-type-arrowRight"
  />Design Path
  <span class="swan-button-description">Short description</span>
</button>

<button
  type="button"
  class="swan-button swan-button-skin-secondary swan-button-with-icon-right swan-button-design-path"
>
  <img
    src="https://swan.prod.merch.vpsvc.com/v2/icons/arrow_right.b75db7a964c0e26c4d1da0075e0a7ad6.svg"
    alt=""
    class="swan-icon swan-icon-size-20p swan-icon-skin-standard swan-icon-type-arrowRight"
  />Design Path
  <span class="swan-button-description">Short description</span>
</button>

Clear Selection

Use skin="clear-selection" for Buttons that show user selections.

These Buttons require visually hidden text inside them which must be localized, to make it clear to assistive technologies what the action of clicking on the button will do.

ReactVanilla

<ClearSelectionButtons>
  <Button skin="clear-selection">
    <VisuallyHidden>Remove</VisuallyHidden>
    Selection
  </Button>
  <ClearAllButton as="button">
    Clear All
    <VisuallyHidden>Selections</VisuallyHidden>
  </ClearAllButton>
</ClearSelectionButtons>

<ClearSelectionButtons>
  <Button skin="clear-selection">
    <VisuallyHidden>Remove</VisuallyHidden>
    Selection
  </Button>
  <ClearAllButton as="button">
    Clear All
    <VisuallyHidden>Selections</VisuallyHidden>
  </ClearAllButton>
</ClearSelectionButtons>

<div class="swan-clear-selection-buttons">
  <button type="button" class="swan-button-skin-clear-selection">
    Selection
  </button>
  <button class="swan-link swan-clear-all-button">Clear All</button>
</div>

<div class="swan-clear-selection-buttons">
  <button type="button" class="swan-button-skin-clear-selection">
    Selection
  </button>
  <button class="swan-link swan-clear-all-button">Clear All</button>
</div>

Button as a Link

Use render for Buttons with the behavior of a Link. Refer to render prop guidelines.

Buttons that take users to a new page should render an <a> instead of a <button> for accessibility requirements.

ReactVanilla

<Button
  render={props => (
    <Link to="#" className={props.className}>
      {props.children}
    </Link>
  )}
>
  I am a link
</Button>

<Button
  render={props => (
    <Link to="#" className={props.className}>
      {props.children}
    </Link>
  )}
>
  I am a link
</Button>

<a href="#" class="swan-button"> I am a link </a>

<a href="#" class="swan-button"> I am a link </a>

Link as a Button

Use render for Links with the behavior of a Button. Refer to render prop guidelines.

Links that perform an action on the current page should render a <button> instead of an <a> for accessibility requirements.

ReactVanilla

<Link
  render={p => (
    <Button skin="link" className={p.className}>
      {p.children}
    </Button>
  )}
>
  I am a button
</Link>

<Link
  render={p => (
    <Button skin="link" className={p.className}>
      {p.children}
    </Button>
  )}
>
  I am a button
</Link>

<button type="button" class="swan-link swan-button-skin-link">
  I am a button
</button>

<button type="button" class="swan-link swan-button-skin-link">
  I am a button
</button>

Unstyled

Use skin="unstyled" for Buttons with no styling.

This variant provides no affordance on touch devices and little affordance on desktops, so should only be used to wrap a component that provides its own affordance.

ReactVanilla

<Button skin="unstyled">Unstyled</Button>

<Button skin="unstyled">Unstyled</Button>

<button type="button" class="swan-button-skin-unstyled">Unstyled</button>

<button type="button" class="swan-button-skin-unstyled">Unstyled</button>

Buttons in Banner

When used inside Banner, Buttons have a different styling to make them more neutral. This allows them to sit on a wide range of colors often used as Banner backgrounds without clashing.

ReactVanilla

<Banner variant="card" height="short">
  <BannerTextContainer>
    <BannerText>
      <BannerTitle>Title line with a message</BannerTitle>
      <BannerDescription>
        <p>
          Description to give a better idea of what is presented on the banner.
        </p>
      </BannerDescription>
      <BannerLinks>
        <Button skin="primary">Button</Button>
        <Button skin="secondary">Button</Button>
        <Button skin="tertiary">Button</Button>
      </BannerLinks>
    </BannerText>
  </BannerTextContainer>
  <BannerImageContainer>
    <BannerImage>
      <FluidImage
        src="https://www.picsum.photos/800/300?id=right"
        alt="Placeholder"
      />
    </BannerImage>
  </BannerImageContainer>
</Banner>

<Banner variant="card" height="short">
  <BannerTextContainer>
    <BannerText>
      <BannerTitle>Title line with a message</BannerTitle>
      <BannerDescription>
        <p>
          Description to give a better idea of what is presented on the banner.
        </p>
      </BannerDescription>
      <BannerLinks>
        <Button skin="primary">Button</Button>
        <Button skin="secondary">Button</Button>
        <Button skin="tertiary">Button</Button>
      </BannerLinks>
    </BannerText>
  </BannerTextContainer>
  <BannerImageContainer>
    <BannerImage>
      <FluidImage
        src="https://www.picsum.photos/800/300?id=right"
        alt="Placeholder"
      />
    </BannerImage>
  </BannerImageContainer>
</Banner>

<div
  class="swan-banner swan-banner-card swan-banner-text-box-horizontal-align-left swan-banner-short"
>
  <div class="swan-banner-text-container">
    <div class="swan-banner-text">
      <p class="swan-banner-title">Title line with a message</p>
      <div class="swan-banner-description">
        <p>
          Description to give a better idea of what is presented on the banner.
        </p>
      </div>
      <div class="swan-banner-links">
        <button type="button" class="swan-button swan-button-skin-primary">
          Button
        </button>
        <button type="button" class="swan-button swan-button-skin-secondary">
          Button
        </button>
        <button type="button" class="swan-button swan-button-skin-tertiary">
          Button
        </button>
      </div>
    </div>
  </div>
  <div class="swan-banner-image-container">
    <div class="swan-banner-image">
      <img
        src="https://www.picsum.photos/800/300?id=right"
        alt="Placeholder"
        class="swan-fluid-image"
      />
    </div>
  </div>
</div>

<div
  class="swan-banner swan-banner-card swan-banner-text-box-horizontal-align-left swan-banner-short"
>
  <div class="swan-banner-text-container">
    <div class="swan-banner-text">
      <p class="swan-banner-title">Title line with a message</p>
      <div class="swan-banner-description">
        <p>
          Description to give a better idea of what is presented on the banner.
        </p>
      </div>
      <div class="swan-banner-links">
        <button type="button" class="swan-button swan-button-skin-primary">
          Button
        </button>
        <button type="button" class="swan-button swan-button-skin-secondary">
          Button
        </button>
        <button type="button" class="swan-button swan-button-skin-tertiary">
          Button
        </button>
      </div>
    </div>
  </div>
  <div class="swan-banner-image-container">
    <div class="swan-banner-image">
      <img
        src="https://www.picsum.photos/800/300?id=right"
        alt="Placeholder"
        class="swan-fluid-image"
      />
    </div>
  </div>
</div>

Skin

Use secondary for all Buttons by default. Multiple secondary actions can be displayed on a page.
Use primary for the main action of the page.
- Limit to a single primary Button per page if possible to guide users through the purchasing flow and help them easily get to the cart.
- Multiple primary buttons can be used for upsell (adding extra items to checkout).
Use tertiary when a more subtle Button is required.
Use destructive-primary if an action will destroy data, usually within a confirmation Modal Dialog.
Use destructive-secondary to indicate an action will destroy data. This action would usually trigger a Modal Dialog confirming the destruction of data.
Use destructive-tertiary when a more subtle Button is required. This action would usually trigger a Modal Dialog confirming the destruction of data.

Content

Use clear, concise labels to describe the action being performed by the Button.
Use sentence case.
Do not use punctuation.
Buttons will grow wide enough to accommodate their content. If there is not enough room for the Button to grow, the text will wrap to the next line.
Ensure Button content is short and succinct to avoid wrapping.

Placement

Place Buttons in flow near relevant content, with negative space to call the maximum amount of attention to the action.
Align Buttons accordingly with the content grouping for visual consistency. For example, left-aligned typography includes a left-aligned Button.

Disabled

Disabling Buttons can confuse users since they afford little feedback. Users may not understand why the Button can’t be clicked, and be blocked progressing through the flow. It is often better to allow a Button to be clicked, then communicate to the user what is blocking them from progressing.

Button vs Link

Use Buttons to perform an action on the current page. Use links to take users to a new page.
Buttons can be styled to appear as a link. Links can be styled to appear as a Button.

Accessibility

Ensure Buttons have appropriate contrast when placed on busy backgrounds.

Props

Button

This component is implemented using the <button /> as the root element. You can utilize the native attributes supported by <button /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
width	`"standard" \| "full-width" \| "wide" \| null`	false	The width variation	standard
loading	`boolean \| null`	false	Activates the loading state. Should be used with a separate live region to provide updates to screen readers.	null
size	`"standard" \| "mini" \| null`	false	⚠️ Deprecated - This is deprecated without a replacement. The size variation	standard
skin	`"link" \| "primary" \| "secondary" \| "unstyled" \| "tertiary" \| "clear-selection" \| "destructive-primary" \| "destructive-secondary" \| "destructive-tertiary" \| null`	false	The visual style of the Button	secondary
specialVariant	`"standard" \| "design-path" \| null`	false	Variations for special cases	standard
iconPosition	`"left" \| "right" \| null`	false	The position of the icon in the Button	null
buttonShape	`"standard" \| "round" \| null`	false	The shape of the Button	standard

ButtonDescription

This component is implemented using the <span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

ClearSelectionButtons

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

ClearAllButton

See core props for additional props that can be applied to this component.

File Input

Button

Use Button...

Don't use Button...

Skin

Size

Width

Disabled

Icons

Loading

Design Path

Clear Selection

Button as a Link

Link as a Button

Unstyled

Buttons in Banner

Skin

Content

Placement

Disabled

Button vs Link

Accessibility

Props

Related