Balance Logo
Balance
Reckon Design System
Open playroom

Button

Buttons are used to trigger actions based on a user's interaction.
Install
pnpm add @balance-web/button
Import usage
import {
  Button,
  IconButton,
  usePreventableClickHandler,
  getButtonStyles
} from '@balance-web/button';
  • Code
  • API

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

<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

<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.

<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.

<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.

<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.

<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.

<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.

// 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.

<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.

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

colorScheme

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

Default value is primary.

<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.

<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.

<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.

<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>

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

<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" />;

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.

<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

<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>
Copyright © 2025 Reckon. Designed and developed in partnership with Thinkmill.
Bitbucket logoJira software logoConfluence logo