The DeprecatedButton package has been deprecated and will be removed in a future version. Use Button instead. There is a migration guide at the bottom of the page.

Button

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

Size

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

Edit in Playroom

<Inline gap="small">
  <DeprecatedButton label="Small" size="small" />
  <DeprecatedButton label="Medium" />
</Inline>

Weight

Reserve bold buttons for primary/important actions on a page or in a view. Subtle buttons should make up most of the interface, while a weight of "none" should be spared for subordinate actions.

Edit in Playroom

<Inline gap="small">
  <DeprecatedButton weight="bold" label="Bold" />
  <DeprecatedButton weight="subtle" label="Subtle" />
  <DeprecatedButton weight="none" label="None" />
</Inline>

Tone

The Button has is available in three tones, active is the default.

active (default)
critical - not to be used when weight is "none"
passive - only to be used when weight is "none"

Active is the default tone, use this to let user know there’s an action they can perform to go to a new view or go to the next step in the flow.

Use the critical tone when an action has potentially destructive effects on the user‘s data (delete, remove, etc). If using the critical tone button as a standalone, we recommend styling it as a subtle button. Within a set, the danger button should be styled as a bold button.

Passive tone can only ever be used when weight is “none”. Always use this next to other buttons and never use it as standalone button.

Edit in Playroom

<Stack gap="medium">
  <Inline gap="small">
    <DeprecatedButton weight="bold" label="Active" />
    <DeprecatedButton weight="subtle" label="Active" />
    <DeprecatedButton weight="none" tone="active" label="Active" />
  </Inline>
  <Inline gap="small">
    <DeprecatedButton weight="bold" tone="critical" label="Critical" />
    <DeprecatedButton weight="subtle" tone="critical" label="Critical" />
  </Inline>
  <Inline gap="small">
    <DeprecatedButton weight="none" tone="passive" label="Passive" />
  </Inline>
</Stack>

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">
  <DeprecatedButton
    size="medium"
    tone="critical"
    label="Delete"
    iconBefore={Trash2Icon}
  />
  <DeprecatedButton
    size="medium"
    weight="subtle"
    label="Edit"
    iconBefore={Edit3Icon}
  />
  <DeprecatedButton label="Continue" iconAfter={ChevronRightIcon} />
  <DeprecatedButton weight="none" label="Add" iconBefore={PlusIcon} />
</Inline>

Disabled

When disabled the button is not interactive to the user.

Edit in Playroom

<Inline gap="small">
  <DeprecatedButton disabled weight="bold" label="Bold" />
  <DeprecatedButton disabled weight="subtle" label="Subtle" />
  <DeprecatedButton disabled weight="none" label="None" />
</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

const [loading, setLoading] = useState(false);
const toggle = (e) => setLoading(e.target.checked);
return (
  <Stack gap="large">
    <Checkbox checked={loading} onChange={toggle}>
      <Text>Toggle loading state</Text>
    </Checkbox>
    <div>
      <DeprecatedButton loading={loading} label="Create employee" />
    </div>
  </Stack>
);

Block

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

Edit in Playroom

<DeprecatedButton block weight="subtle" 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">
  <DeprecatedButton label="Create job" />
  <DeprecatedButton weight="none" tone="passive" label="Cancel" />
</Stack>

IconButton

The icon button variant shares its rules regarding weight, size and tone 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

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

Size

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

Edit in Playroom

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

Weight

The IconButton is available in three weights, bold is the default.

Edit in Playroom

<Inline gap="small">
  <DeprecatedIconButton weight="bold" label="Bold" icon={FeatherIcon} />
  <DeprecatedIconButton weight="subtle" label="Subtle" icon={FeatherIcon} />
  <DeprecatedIconButton weight="none" label="None" icon={FeatherIcon} />
</Inline>

Disabled

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

Edit in Playroom

<Inline gap="small">
  <DeprecatedIconButton disabled weight="bold" label="Bold" icon={SlashIcon} />
  <DeprecatedIconButton
    disabled
    weight="subtle"
    label="Subtle"
    icon={SlashIcon}
  />
  <DeprecatedIconButton disabled weight="none" label="None" icon={SlashIcon} />
</Inline>

Tone

The IconButton is available in three tones, active is the default.

Edit in Playroom

<Inline gap="small">
  <DeprecatedIconButton
    icon={InfoIcon}
    tone="active"
    weight="bold"
    label="Active"
  />
  <DeprecatedIconButton
    icon={AlertOctagonIcon}
    tone="critical"
    weight="subtle"
    label="Critical"
  />
  <DeprecatedIconButton
    icon={HelpCircleIcon}
    tone="passive"
    weight="none"
    label="Passive"
  />
</Inline>

ActionButton

Action buttons allow users to perform an action. They’re used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren’t meant to draw a lot of attention.

Edit in Playroom

<ActionButton label="Action" />

Weight

Where two or more actions are available you may want to emphasise one action over others. Use the subtle weight variant to drop the border.

Edit in Playroom

<Inline gap="small">
  <ActionButton label="Bold" />
  <ActionButton label="Subtle" weight="subtle" />
</Inline>

Icons

Action buttons accept icons before and after the label.

Edit in Playroom

<Inline gap="small">
  <ActionButton label="Edit" iconBefore={Edit3Icon} />
  <ActionButton label="More" iconAfter={ChevronDownIcon} />
</Inline>

Children

Provide arbitrary element(s) to the button. The icon* and label properties will no-longer apply.

Edit in Playroom

<ActionButton>
  <Inline gap="small" alignY="center">
    <Text size="small" weight="medium">
      Count
    </Text>
    <NotificationBadge value={123} tone="informative" />
  </Inline>
</ActionButton>

Icon only action button

We can use the children support to render an icon only action button.

NOTE: You must provide aria-label to the button in order for it to be accessible to screen readers.

Edit in Playroom

<Inline>
  <ActionButton weight="bold" aria-label="Settings">
    <SettingsIcon aria-label="123" size="small" />
  </ActionButton>
</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

<DeprecatedButton 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';
<DeprecatedButton 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.

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

Button Deprecated

Size

Weight

Tone

Icons

Disabled

Loading

Block

IconButton

Required props

Size

Weight

Disabled

Tone

ActionButton

Weight

Icons

Children

Icon only action button

Button links

Migration guide