⚠️ After March 18, 2024, the FastStore documentation will be migrated to the Developer Portal. For more information, access the official release note.

Button

Buttons indicate actions that users can take, such as adding an item to the cart, submitting a form, and proceeding with an operation.

Overview


Import

Import the component from @faststore/ui

import { Button } from '@faststore/ui'

Import Styles into your FastStore project

To apply the styles of this component in your FastStore project, import the following into your stylesheet:

@import '@faststore/ui/src/components/atoms/Button/styles.scss';

Follow the instructions in the Importing FastStore UI component styles tutorial.


Usage

<Button variant="primary">Add to Cart</Button>

Props

NameTypeDescriptionDefault
testIdstringID to find this component in testing tools (e.g.: cypress, testing library, and jest).fs-button
variant"primary" | "secondary" | "tertiary"Specifies the component color variant.
size"small" | "regular"Specifies the size variant.regular
inversefalse | trueDefines the use of inverted colors.
disabledfalse | trueSpecifies that this button should be disabled.
iconstring | number | false | true | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortalA React component that will be rendered as an icon.
loadingfalse | trueBoolean that represents a loading state.
loadingLabelstringSpecifies a label for loading state.
iconPosition"left" | "right"Specifies where the icon should be positionedleft

Design Tokens

Local tokenDefault value/Global token linked
--fs-button-paddingcalc(var(--fs-spacing-1) - (var(--fs-button-border-width) * 2)) var(--fs-spacing-3)
--fs-button-heightvar(--fs-control-tap-size)
--fs-button-gapvar(--fs-spacing-2)
--fs-button-shadowvar(--fs-shadow)
--fs-button-shadow-hovervar(--fs-button-shadow)
--fs-button-border-radiusvar(--fs-border-radius)
--fs-button-border-widthvar(--fs-border-width-thick)
--fs-button-border-color
transparent
--fs-button-text-sizevar(--fs-text-size-base)
--fs-button-text-weightvar(--fs-text-weight-bold)
--fs-button-transition-functionvar(--fs-transition-function)
--fs-button-transition-propertyvar(--fs-transition-property)
--fs-button-transition-timingvar(--fs-transition-timing)

Nested Elements

Icon

<Button
  variant="primary"
  icon={<Icon name="ShoppingCart" />}
  iconPosition="left"
>
  Add to Cart
</Button>
Local tokenDefault value/Global token linked
--fs-button-icon-padding0 var(--fs-spacing-1)

Hierarchy

Primary

<Button variant="primary">Button</Button>
Local tokenDefault value/Global token linked
--fs-button-primary-text-color
var(--fs-color-primary-text)
--fs-button-primary-text-color-hover
var(--fs-button-primary-text-color)
--fs-button-primary-text-color-active
var(--fs-button-primary-text-color)
--fs-button-primary-bkg-color
var(--fs-color-primary-bkg)
--fs-button-primary-bkg-color-hover
var(--fs-color-primary-bkg-hover)
--fs-button-primary-bkg-color-active
var(--fs-color-primary-bkg-active)
--fs-button-primary-border-color
transparent
--fs-button-primary-border-color-hover
var(--fs-button-primary-border-color)
--fs-button-primary-border-color-active
var(--fs-button-primary-border-color)
--fs-button-primary-shadow-hovervar(--fs-button-shadow-hover)

Primary Inverse

<Button inverse variant="primary">
  Button
</Button>
Local tokenDefault value/Global token linked
--fs-button-primary-inverse-text-color
var(--fs-button-primary-bkg-color)
--fs-button-primary-inverse-text-color-hover
var(--fs-button-primary-bkg-color)
--fs-button-primary-inverse-text-color-active
var(--fs-button-primary-bkg-color)
--fs-button-primary-inverse-bkg-color
var(--fs-button-primary-text-color)
--fs-button-primary-inverse-bkg-color-hover
var(--fs-color-primary-bkg-light)
--fs-button-primary-inverse-bkg-color-active
var(--fs-color-primary-bkg-light-active)
--fs-button-primary-inverse-border-color
var(--fs-button-primary-border-color)
--fs-button-primary-inverse-border-color-hover
var(--fs-button-primary-border-color)
--fs-button-primary-inverse-border-color-active
var(--fs-button-primary-border-color)
--fs-button-primary-inverse-shadow-hovervar(--fs-button-shadow-hover)

Secondary

<Button variant="secondary">Button</Button>
Local tokenDefault value/Global token linked
--fs-button-secondary-text-color
var(--fs-color-secondary-text)
--fs-button-secondary-text-color-hover
var(--fs-color-text-inverse)
--fs-button-secondary-text-color-active
var(--fs-button-secondary-text-color-hover)
--fs-button-secondary-bkg-color
var(--fs-color-secondary-bkg)
--fs-button-secondary-bkg-color-hover
var(--fs-color-secondary-bkg-hover)
--fs-button-secondary-bkg-color-active
var(--fs-color-secondary-bkg-active)
--fs-button-secondary-border-color
var(--fs-button-secondary-text-color)
--fs-button-secondary-border-color-hover
var(--fs-button-secondary-bkg-color-hover)
--fs-button-secondary-border-color-active
var(--fs-button-secondary-bkg-color-active)
--fs-button-secondary-shadow-hovervar(--fs-button-shadow-hover)

Secondary Inverse

<Button inverse variant="secondary">
  Button
</Button>
Local tokenDefault value/Global token linked
--fs-button-secondary-inverse-text-color
var(--fs-button-secondary-text-color-hover)
--fs-button-secondary-inverse-text-color-hover
var(--fs-button-secondary-text-color)
--fs-button-secondary-inverse-text-color-active
var(--fs-button-secondary-inverse-text-color-hover)
--fs-button-secondary-inverse-bkg-color
var(--fs-button-secondary-bkg-color)
--fs-button-secondary-inverse-bkg-color-hover
var(--fs-button-secondary-text-color-hover)
--fs-button-secondary-inverse-bkg-color-active
var(--fs-color-secondary-bkg-light)
--fs-button-secondary-inverse-border-color
var(--fs-button-secondary-inverse-text-color)
--fs-button-secondary-inverse-border-color-hover
var(--fs-button-secondary-inverse-bkg-color-hover)
--fs-button-secondary-inverse-border-color-active
var(--fs-button-secondary-inverse-bkg-color-hover)
--fs-button-secondary-inverse-shadow-hovervar(--fs-button-shadow-hover)

Tertiary

<Button variant="tertiary">Button</Button>
Local tokenDefault value/Global token linked
--fs-button-tertiary-text-color
var(--fs-color-tertiary-text)
--fs-button-tertiary-text-color-hover
var(--fs-button-tertiary-text-color)
--fs-button-tertiary-text-color-active
var(--fs-button-primary-bkg-color)
--fs-button-tertiary-bkg-color
var(--fs-color-tertiary-bkg)
--fs-button-tertiary-bkg-color-hover
var(--fs-color-tertiary-bkg-hover)
--fs-button-tertiary-bkg-color-active
var(--fs-color-tertiary-bkg-active)
--fs-button-tertiary-border-color
transparent
--fs-button-tertiary-border-color-hover
var(--fs-button-tertiary-border-color)
--fs-button-tertiary-border-color-active
var(--fs-button-tertiary-border-color)
--fs-button-tertiary-shadow-hovervar(--fs-button-shadow-hover)

Tertiary Inverse

<Button inverse variant="tertiary">
  Button
</Button>
Local tokenDefault value/Global token linked
--fs-button-tertiary-inverse-text-color
var(--fs-button-secondary-text-color-hover)
--fs-button-tertiary-inverse-text-color-hover
var(--fs-button-secondary-text-color-hover)
--fs-button-tertiary-inverse-text-color-active
var(--fs-button-secondary-text-color-hover)
--fs-button-tertiary-inverse-bkg-color
var(--fs-button-secondary-inverse-bkg-color)
--fs-button-tertiary-inverse-bkg-color-hover
var(--fs-button-primary-bkg-color-hover)
--fs-button-tertiary-inverse-bkg-color-active
var(--fs-button-primary-bkg-color-active)
--fs-button-tertiary-inverse-border-color
var(--fs-button-tertiary-border-color)
--fs-button-tertiary-inverse-border-color-hover
var(--fs-button-tertiary-border-color)
--fs-button-tertiary-inverse-border-color-active
var(--fs-button-tertiary-border-color)
--fs-button-tertiary-inverse-shadow-hovervar(--fs-button-shadow-hover)

Variants

Disabled

<Button variant="primary" disabled>
  Button
</Button>
Local tokenDefault value/Global token linked
--fs-button-disabled-bkg-color
var(--fs-color-disabled-bkg)
--fs-button-disabled-text-color
var(--fs-color-disabled-text)

Loading

Local tokenDefault value/Global token linked
--fs-button-loading-label-column-gapvar(--fs-spacing-3)

Small

<Button variant="primary" size="small">
  Button
</Button>
<Button variant="primary" size="small" icon={<Icon name="ShoppingCart" />}>
  Button
</Button>
Local tokenDefault value/Global token linked
--fs-button-small-paddingvar(--fs-spacing-0) var(--fs-spacing-1)
--fs-button-small-min-heightvar(--fs-spacing-5)
--fs-button-small-gapvar(--fs-spacing-1)
--fs-button-small-icon-widthvar(--fs-spacing-3)
--fs-button-small-icon-heightvar(--fs-button-small-icon-width)

Use Cases

Use the Button component to communicate user actions on the following components:

  • Buy-now and add-to-cart buttons on Product Cards
  • Call-to-action buttons on Cards
  • Submit and/or withdraw actions on Forms
  • Submit and/or withdraw actions on Modal windows.

Customization

For further customization, you can use the following data attributes:

data-fs-button

data-fs-button-variant="primary | secondary | tertiary"

data-fs-button-inverse

data-fs-button-size="small | regular"

data-fs-button-loading="true"


Best Practices

✅ Do's

  • Use standard button designs and shapes to make your button look clickable.
  • Use styles to communicate the importance of an action by visually differentiating Primary and Secondary buttons.
  • Make buttons finger-friendly for mobile users and large enough for reliable interactions. Generally, touch targets are at least 44 by 44 CSS pixels.
  • Use task-specific words to write button labels.
  • Place the buttons in an order that reflects a conversation between the user and the system.
  • Provide visual or audio feedback on interactions. Whenever a user interacts with a button, the button should change its state and let the user know that something is happening as a consequence.
  • Define a style system for your button states (i.e., normal, focus, hover, active, pressed, disabled).
  • Use icon-only buttons only for widespread actions with highly standardized icons, such as a cross for close.
  • Use the aria-label attribute to provide a textual alternative for icon-only buttons.

❌ Don'ts

  • Don’t make users hunt for buttons. Place buttons where users expect to see them or can easily find them.
  • Don't rely on icons to communicate complex actions.
  • Don't use generic words that can potentially confuse users.
  • Avoid cluttering the UI with too many buttons.
  • Avoid having more than one Primary action button on the screen at a time.
  • Avoid using disabled buttons, if possible. Instead, give preference to hiding the unavailable option.
  • Don't place buttons next to Badges. Although badges and buttons are similar in appearance, badges are not interactive and may confuse users if not used in the proper context.
  • Don't use Buttons as Links. Links are not intended to invite users to take action. Instead, they redirect users somewhere.
  • Avoid using aria-label when the button already has a label.

Related components

  • Icon Button

    A button which content is only an icon, without any label.

    See more
  • Buy Button

    A button with the intent of directly sending the user to the checkout/cart step.

    See more
  • Link Button

    Is similar to a button, however acts as a link to navigate users between pages.

    See more