Buttons allow users to perform an action or to navigate to another page / view. Buttons let users understand what will happen next.

Alternatives

SplitButton — For grouping related actions together.

colorScheme

Color scheme are used to indicate the importance of an action.

Default value is primary

Edit in Playroom

<Inline gap="small">
  <Button colorScheme="primary" label="Primary" />
  <Button colorScheme="secondary" label="Secondary" />
  <Button colorScheme="tertiary" label="Tertiary" />
  <Button colorScheme="critical" label="Critical" />
</Inline>

variant

Variant are used to change the visual style of a button.

Default value is filled

Edit in Playroom

<Inline gap="medium">
  <Button variant="filled" label="Filled" />
  <Button variant="outline" label="Outline" />
  <Button variant="text" label="Text" />
</Inline>

size

The Button is available in three sizes.

Default value is medium.

Edit in Playroom

<Inline gap="small">
  <Button label="Small" size="small" />
  <Button label="Medium" />
  <Button label="Large" size="large" />
</Inline>

disabled

When disabled the button is not interactive to the user.

Edit in Playroom

<Inline gap="small">
  <Button disabled variant="filled" label="Filled" />
  <Button disabled variant="outline" label="Outline" />
  <Button disabled variant="text" label="Text" />
</Inline>

loading

Use the loading property to indicate that an action is in progress. Note that buttons are not interactive whilst loading.

Edit in Playroom

<Inline gap="large">
  <Button loading={true} label="Create employee" />
  <Button
    loading={true}
    colorScheme="secondary"
    variant="outline"
    label="Create employee"
  />
  <Button
    loading={true}
    colorScheme="tertiary"
    variant="text"
    label="Create employee"
  />
</Inline>

block

Use the block property to make the button fill its container.

Edit in Playroom

<Button block variant="outline" label="Generate report" />

This is more commonly achieved by wrapping multiple buttons with the Stack component, which will automatically make the buttons fill their container.

Edit in Playroom

<Stack gap="small">
  <Button label="Create job" />
  <Button colorScheme="tertiary" variant="text" label="Cancel" />
</Stack>

dataTestId

Use the data-testid property to add test ids to your buttons. Callers are responsible to set unique ids when buttons are used in a collection.

Edit in Playroom

// Single use
<Stack>
  <Button label="Create pay run" data-testid="create-payrun" />
</Stack>

borderRadius, borderLeftWidth, borderTopWidth, borderRightWidth, borderBottomWidth

These props are used to directly control the border css of the button.

Icons

Icons can be used in buttons when additional clarity is required and the icon is highly relevant to the action. Avoid using two icons in a button.

Use iconBefore to help the user learn about the action of the button quickly or to indicate the user will go back to previous step in the flow.

Use iconAfter to help the user learn if there is a change in the flow (open new tab or window for example) or to indicate the user will go to next step in the flow.

Edit in Playroom

<Inline gap="small">
  <Button
    size="medium"
    colorScheme="critical"
    label="Delete"
    iconBefore={Trash2Icon}
  />
  <Button size="medium" variant="outline" label="Edit" iconBefore={Edit3Icon} />
  <Button label="Continue" iconAfter={ChevronRightIcon} />
  <Button variant="text" label="Add" iconBefore={PlusIcon} />
</Inline>

IconButton

The icon button shares its rules regarding colorScheme, variant and size with the standard button. For brevity we won't duplicate them here; refer to the above documentation where applicable.

Required props

The IconButton requires an icon property, which must be a component from the icon package.

A label is required to support accessibility. Describe the action or effect that will take place when the button is clicked.

Edit in Playroom

<IconButton icon={Edit3Icon} label="Edit pay run" />

colorScheme

Color scheme are used to indicate the importance of an action.

Default value is primary.

Edit in Playroom

<Inline gap="small">
  <IconButton
    icon={InfoIcon}
    colorScheme="primary"
    variant="filled"
    label="Active"
  />
  <IconButton
    icon={AlertOctagonIcon}
    colorScheme="critical"
    variant="outline"
    label="Critical"
  />
  <IconButton
    icon={HelpCircleIcon}
    colorScheme="tertiary"
    variant="text"
    label="Passive"
  />
</Inline>

variant

The IconButton is available in three variants, filled is the default.

Edit in Playroom

<Inline gap="small">
  <IconButton variant="filled" label="Filled" icon={FeatherIcon} />
  <IconButton variant="outline" label="Outline" icon={FeatherIcon} />
  <IconButton variant="text" label="Text" icon={FeatherIcon} />
</Inline>

size

The IconButton is available in two sizes, medium is the default.

Edit in Playroom

<Inline gap="small">
  <IconButton size="small" icon={BoxIcon} label="Small" />
  <IconButton size="medium" icon={BoxIcon} label="Medium" />
  <IconButton size="large" icon={BoxIcon} label="Large" />
</Inline>

disabled

When disabled the button will not be interactive to the user.

Edit in Playroom

<Inline gap="small">
  <IconButton variant="filled" label="Filled" icon={FeatherIcon} disabled />
  <IconButton variant="outline" label="Outline" icon={FeatherIcon} disabled />
  <IconButton variant="text" label="Text" icon={FeatherIcon} disabled />
</Inline>

Button links

To have a link that looks like a button, use the as prop to render an <a> instead of a <button>.

Edit in Playroom

<Button as="a" href="#" label="Button component as link" />

If you're doing client side routing using Next, use as={NextLink} instead of as="a".

import { Button } from '@balance-web/button-deprecated';
import { NextLink } from '@balance-web/next-link';
<Button as={NextLink} href="/" label="Button component a link" />;

children

It is possible to completely take over the rendering of the button content by providing children. In this case the consumer is responsible make sure the text, sizing and spacing is all consistent with the button being rendered.

You should still provide an appropriate label string for accessibility reasons.

Migration guide

Below is a mapping from DeprecatedButton to the new Button component. This mapping is about the tone and weight props on DeprecatedButton to colorScheme and variant props on Button. All other props should behave the same.

If this mapping doesn't cover a particular scenario, talk to a design.

Edit in Playroom

<Stack gap="medium">
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="bold" tone="active" />
    <Button label="New" colorScheme="primary" variant="filled" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="subtle" tone="active" />
    <Button label="New" colorScheme="primary" variant="outline" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="none" tone="active" />
    <Button label="New" colorScheme="primary" variant="text" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="bold" tone="critical" />
    <Button label="New" colorScheme="critical" variant="filled" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="subtle" tone="critical" />
    <Button label="New" colorScheme="critical" variant="outline" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="none" tone="critical" />
    <Button label="New" colorScheme="critical" variant="text" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="bold" tone="passive" />
    <Button label="New" colorScheme="tertiary" variant="outline" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="subtle" tone="passive" />
    <Button label="New" colorScheme="tertiary" variant="outline" />
  </Inline>
  <Inline gap="xxlarge">
    <DeprecatedButton label="Old" weight="none" tone="passive" />
    <Button label="New" colorScheme="tertiary" variant="text" />
  </Inline>
  <Inline gap="xxlarge">
    <ActionButton label="Old action button" />
    <Button
      label="New action button"
      colorScheme="tertiary"
      variant="outline"
    />
  </Inline>
  <Inline gap="xxlarge">
    <ActionButton label="Old action button" weight="subtle" />
    <Button label="New action button" colorScheme="tertiary" variant="text" />
  </Inline>
</Stack>

All color schemes, variants and states

Edit in Playroom

<Stack gap="xxlarge" width={600}>
  <Columns gap="large">
    <div></div>
    <Text size="xsmall" weight="bold" color="muted">
      Default
    </Text>
    <Text size="xsmall" weight="bold" color="muted">
      Loading
    </Text>
    <Text size="xsmall" weight="bold" color="muted">
      Disabled
    </Text>
  </Columns>
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Primary filled
      </Text>
      <Button label="Label" colorScheme="primary" variant="filled" />
      <Button label="Label" colorScheme="primary" variant="filled" loading />
      <Button label="Label" colorScheme="primary" variant="filled" disabled />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Primary outline
      </Text>
      <Button label="Label" colorScheme="primary" variant="outline" />
      <Button label="Label" colorScheme="primary" variant="outline" loading />
      <Button label="Label" colorScheme="primary" variant="outline" disabled />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Primary text
      </Text>
      <Button label="Label" colorScheme="primary" variant="text" />
      <Button label="Label" colorScheme="primary" variant="text" loading />
      <Button label="Label" colorScheme="primary" variant="text" disabled />
    </Columns>
  </Stack>
  <Divider />
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Secondary filled
      </Text>
      <Button label="Label" colorScheme="secondary" variant="filled" />
      <Button label="Label" colorScheme="secondary" variant="filled" loading />
      <Button label="Label" colorScheme="secondary" variant="filled" disabled />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Secondary outline
      </Text>
      <Button label="Label" colorScheme="secondary" variant="outline" />
      <Button label="Label" colorScheme="secondary" variant="outline" loading />
      <Button
        label="Label"
        colorScheme="secondary"
        variant="outline"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Secondary text
      </Text>
      <Button label="Label" colorScheme="secondary" variant="text" />
      <Button label="Label" colorScheme="secondary" variant="text" loading />
      <Button label="Label" colorScheme="secondary" variant="text" disabled />
    </Columns>
  </Stack>
  <Divider />
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Tertiary filled
      </Text>
      <Button label="Label" colorScheme="tertiary" variant="filled" />
      <Button label="Label" colorScheme="tertiary" variant="filled" loading />
      <Button label="Label" colorScheme="tertiary" variant="filled" disabled />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Tertiary outline
      </Text>
      <Button label="Label" colorScheme="tertiary" variant="outline" />
      <Button label="Label" colorScheme="tertiary" variant="outline" loading />
      <Button label="Label" colorScheme="tertiary" variant="outline" disabled />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Tertiary text
      </Text>
      <Button label="Label" colorScheme="tertiary" variant="text" />
      <Button label="Label" colorScheme="tertiary" variant="text" loading />
      <Button label="Label" colorScheme="tertiary" variant="text" disabled />
    </Columns>
  </Stack>
  <Divider />
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Critical filled
      </Text>
      <Button label="Label" colorScheme="critical" variant="filled" />
      <Button label="Label" colorScheme="critical" variant="filled" loading />
      <Button label="Label" colorScheme="critical" variant="filled" disabled />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Critical outline
      </Text>
      <Button label="Label" colorScheme="critical" variant="outline" />
      <Button label="Label" colorScheme="critical" variant="outline" loading />
      <Button label="Label" colorScheme="critical" variant="outline" disabled />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Critical text
      </Text>
      <Button label="Label" colorScheme="critical" variant="text" />
      <Button label="Label" colorScheme="critical" variant="text" loading />
      <Button label="Label" colorScheme="critical" variant="text" disabled />
    </Columns>
  </Stack>
  <Divider />
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Primary filled
      </Text>
      <IconButton icon={PackageIcon} label="Label" colorScheme="primary" />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="primary"
        variant="filled"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Primary outline
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="primary"
        variant="outline"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="primary"
        variant="outline"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Primary text
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="primary"
        variant="text"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="primary"
        variant="text"
        disabled
      />
    </Columns>
  </Stack>
  <Divider />
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Secondary filled
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="secondary"
        variant="filled"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="secondary"
        variant="filled"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Secondary outline
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="secondary"
        variant="outline"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="secondary"
        variant="outline"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Secondary text
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="secondary"
        variant="text"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="secondary"
        variant="text"
        disabled
      />
    </Columns>
  </Stack>
  <Divider />
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Tertiary filled
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="tertiary"
        variant="filled"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="tertiary"
        variant="filled"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Tertiary outline
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="tertiary"
        variant="outline"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="tertiary"
        variant="outline"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Tertiary text
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="tertiary"
        variant="text"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="tertiary"
        variant="text"
        disabled
      />
    </Columns>
  </Stack>
  <Divider />
  <Stack gap="small">
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Critical filled
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="critical"
        variant="filled"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="critical"
        variant="filled"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Critical outline
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="critical"
        variant="outline"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="critical"
        variant="outline"
        disabled
      />
    </Columns>
    <Columns gap="large" alignY="center">
      <Text size="xsmall" weight="bold" color="muted">
        Critical text
      </Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="critical"
        variant="text"
      />
      <Text> N/A</Text>
      <IconButton
        icon={PackageIcon}
        label="Label"
        colorScheme="critical"
        variant="text"
        disabled
      />
    </Columns>
  </Stack>
</Stack>