Button

import { Button, IconButton, usePreventableClickHandler, getButtonStyles } from '@balance-web/button';

colorScheme

Default value is primary

variant

Default value is filled

size

The Button is available in three sizes.

Default value is medium.

disabled

When disabled the button is not interactive to the user.

loading

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

block

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

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

data-testid

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.

borderRadius, borderLeftWidth, borderTopWidth, borderRightWidth, borderBottomWidth

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

Icons

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.

colorScheme

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

Default value is primary.

variant

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

size

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

disabled

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

Button links

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

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.

All color schemes, variants and states

Building on Button

getButtonStyles and usePreventableClickHandler are what Button and IconButton are built from — used directly by button-deprecated and Chip's menu variant to get button-shaped styling and behaviour without rendering Button itself.

usePreventableClickHandler(props, disabled) is why a "disabled" button in this system is never a real disabled attribute: a genuinely disabled element can't be focused or hovered, which would break tooltips explaining why it's disabled. Instead, the handler swallows the click while the button stays focusable and stylable as disabled.

getButtonStyles(props) takes the same style-relevant props Button accepts (colorScheme, variant, size, block, border overrides, …) and returns the CSS object — reach for it if you're building a button-like component that shouldn't wrap Button directly.