ToggleButton

Copy for LLM

The ToggleButton component is a button that can be toggled on or off. It is used to represent a binary choice. It can be used singularly or within a ToggleButtonGroup.

Import

import { ToggleButton, ToggleButtonGroup } from "@cfa/react-core";

Live Editor

Guidelines

When to use

ToggleButton is for a binary on/off action whose selected state persists, such as filters, view modes, and text formatting.

Do

Use clear, simple iconography or short text labels. Keep the option count low so the set does not read like navigation.
For a filter set, multiple ToggleButtons may stay selected at once when multi-select filters are needed.
For a view mode switcher, treat it as a single-select group with exactly one selected option, such as list versus grid.
Persist filter or view-mode selected state in the URL or app state when the choice should survive reload or sharing.
Provide an aria-label on an icon-only view-mode group so the control has a name without visible text.

Avoid

Using ToggleButton for a one-shot action. Use Button.
Using ToggleButton for mutually exclusive named options that are not on or off. Use RadioGroup.

Examples: Single

Events

ToggleButton supports all user interactions via mouse, keyboard, and touch events with the onPress prop. This is similar to the onClick event, but not limited to mouse events. In addition, the onPressStart, onPressEnd, and onPressChange events are also supported. These events are triggered when the user presses, releases, or changes the state of the button.

Autofocus

The autoFocus prop allows the ToggleButton to receive focus when the page loads.

Default Selected

The defaultSelected prop sets the initial selected state of the ToggleButton.

Disabled

The isDisabled prop disables the ToggleButton, preventing user interaction.

Controlled

The isSelected prop sets the selected state of the ToggleButton, helpful when controlled by state.

Size

The size prop sets the size of the ToggleButton. Available sizes are sm, md, and lg.

When a ToggleButton is rendered inside a ToggleButtonGroup, its size prop is ignored. Set size on the group instead so every button in the group uses the same dimensions.

Examples: Group

Set size on ToggleButtonGroup to control sizing for every button in the group. Child ToggleButton size props are not used inside a group.

Default

Controlled

Disabled

You can set a single ToggleButton or the entire ToggleButtonGroup to disabled via the isDisabled prop.

Full Width

Use the fullWidth prop to have the ToggleButtonGroup span the entire width available.

Orientation

Set the orientation prop to one of the following options: "horizontal" by default, or "vertical".

Selection Mode

The selectionMode prop allows for "single" | "multiple". A "single" selection within a ToggleButtonGroup requires the Group’s children to have unique id’s.

Separators

ToggleButtonGroup are separated by dividers by default. To hide the dividers set the noSeparators prop.