1. Components
  2. Buttons
  3. Toggle Button

Toggle Button

Toggle Buttons allow users to toggle a selection on or off.

Aria docsAria API ReferenceReport an issueEdit this page
<ToggleButton>
  <PinIcon />
</ToggleButton>

Installation

npx dotui-cli@latest add toggle-button

Usage

Toggle button allow users to toggle a selection on or off, for example, switching between two states or modes.
They can have a label, an icon, or both. An icon is provided by passing an icon component as child to the ToggleButton or by using the prefix and suffix props. A visible label can be provided by passing a string as a child.

Options

Variants

Use the variant prop to control the visual style of the toggle button. The default size is "quiet".

<ToggleButton variant="quiet"><PinIcon /></ToggleButton>
<ToggleButton variant="outline"><PinIcon /></ToggleButton>
<ToggleButton variant="accent"><PinIcon /></ToggleButton>

Sizes

Use the size prop to control the size of the toggle button.
The default size is "md".

<ToggleButton size="sm"><PinIcon /></ToggleButton>
<ToggleButton size="md"><PinIcon /></ToggleButton>
<ToggleButton size="lg"><PinIcon /></ToggleButton>

Shapes

Use the shape prop to control the shape of the toggle button. The default shape is "rectangle".
Icon-only toggle buttons should include an aria-label.

<ToggleButton shape="square"><PinIcon /></ToggleButton>
<ToggleButton shape="circular"><PinIcon /></ToggleButton>
<ToggleButton prefix={<PinIcon />} shape="rectangle">Pin</ToggleButton>

Disabled

Use the isDisabled prop to disable the toggle button.

<ToggleButton isDisabled><PinIcon /></ToggleButton>

Uncontrolled

Use the defaultSelected to set the initial state of the toggle button.

<ToggleButton defaultSelected><PinIcon /></ToggleButton>

Controlled

Use the isSelected and onChange props to control the state of the toggle button.

state: On
const [isSelected, setSelected] = React.useState(true);
return (
  <ToggleButton isSelected={isSelected} onChange={setSelected}>
    <PinIcon className="rotate-45" />
  </ToggleButton>
);

API Reference

PropTypeDefaultDescription
variant
"quiet" | "outline" | "accent"
"quiet"
The visual style of the button.
size
"sm" | "md" | "lg"
"md"
The size of the button.
shape
"rectangle" | "square" | "circle"
"square"
The visual shape of the button.
prefix
React.ReactNode
-
A visual to display before the button text.
suffix
React.ReactNode
-
A visual to display after the button text.
isSelected
boolean
-
Whether the element should be selected (controlled).
defaultSelected
boolean
-
Whether the element should be selected (uncontrolled).
isDisabled
boolean
-
Whether the button is disabled.
autoFocus
boolean
-
Whether the element should receive focus on render.
type
'button' | 'submit' | 'reset'
-
The behavior of the button when used in an HTML form.
children
ReactNode | (values: ToggleButtonRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode
-
The children of the component. A function may be provided to alter the children based on component state.
className
string
-
The CSS className for the element.
style
CSSProperties | (values: ToggleButtonRenderProps & {defaultStyle: CSSProperties}) => CSSProperties
-
The inline style for the element. A function may be provided to compute the style based on component state.
EventTypeDescription
onChange
(isSelected: boolean) => void
Handler that is called when the element's selection state changes.
onPress
(e: PressEvent) => void
Handler that is called when the press is released over the target.
onPressStart
(e: PressEvent) => void
Handler that is called when a press interaction starts.
onPressEnd
(e: PressEvent) => void
Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target.
onPressChange
(isPressed: boolean) => void
Handler that is called when the press state changes.
onPressUp
(e: PressEvent) => void
Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocus
(e: FocusEvent<Target>) => void
Handler that is called when the element receives focus.
onBlur
(e: FocusEvent<Target>) => void
Handler that is called when the element loses focus.
onFocusChange
(isFocused: boolean) => void
Handler that is called when the element's focus status changes.
onKeyDown
(e: KeyboardEvent) => void
Handler that is called when a key is pressed.
onKeyUp
(e: KeyboardEvent) => void
Handler that is called when a key is released.
onHoverStart
(e: HoverEvent) => void
Handler that is called when a hover interaction starts.
onHoverEnd
(e: HoverEvent) => void
Handler that is called when a hover interaction ends.
onHoverChange
(isHovering: boolean) => void
Handler that is called when the hover state changes.
Data attributeDescription
[data-selected]
Whether the button is currently selected.
[data-hovered]
Whether the button is currently hovered with a mouse.
[data-pressed]
Whether the button is currently in a pressed state.
[data-focused]
Whether the button is focused, either via a mouse or keyboard.
[data-focus-visible]
Whether the button is keyboard focused.
[data-disabled]
Whether the button is disabled.

Accessibility

Keyboard interactions

KeyDescription
Space
Activates/deactivates the toggle.
Enter
Activates/deactivates the toggle.

Last updated on 10/11/2024

ButtonFile Trigger