Toggle button
Material 3 toggle-button guidance, controlled selection, variants, expressive sizes, and web pressed semantics.
Toggle buttons are button-shaped controls with persistent selected state. Use them when pressing the control changes an on/off choice that remains visible after activation; use an ordinary button when the action is momentary.
import { FilledTonalToggleButton } from '@m3-ui/ui';
const [selected, setSelected] = useState(false);
<FilledTonalToggleButton
isSelected={selected}
onChange={setSelected}
>
Pin
</FilledTonalToggleButton>When to use
Use a toggle button for persistent toolbar-like or action-like selection such as pinning or enabling a mode. For independent form choices, prefer Checkbox or Switch according to the Material interaction model. For a mutually exclusive set of adjacent choices, use the appropriate segmented/connected selection component.
Variants
The public family exposes ToggleButton, ElevatedToggleButton, FilledTonalToggleButton, and OutlinedToggleButton. Choose the visual variant from action hierarchy while keeping selection semantics unchanged.
Controlled selection
Selection is explicit application state through isSelected and onChange. The component does not maintain a competing selected-state machine, so the rendered Material state always follows the current controlled value.
Do not use isSelected merely to force a pressed-looking style after a normal action. It represents persistent selection.
Sizes and icons
All variants support the audited Material expressive size vocabulary: extraSmall, small, medium, large, and extraLarge. startIcon participates in the component's canonical icon/spacing geometry.
Choose a semantic size rather than reproducing token dimensions in consumer CSS.
Behavior and states
Checked, unchecked, pressed, hovered, focused, and disabled presentation comes from the component token/runtime mapping. Selected and pressed shape transitions follow the audited renderer path; reduced-motion preference removes transition timing without changing the controlled final state.
Accessibility
On the web, m3-ui intentionally uses React Aria ToggleButton, which exposes native button interaction with aria-pressed. This differs from Compose's runtime projection while preserving the user-facing persistent toggle concept.
Browser-standard Enter/Space activation, focus-visible behavior, and disabled handling come from React Aria. Visible text should identify the toggled property or action consistently.
API reference
ToggleButton
ToggleButton(props: ToggleButtonProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
isSelected* | boolean | — | — | @m3-ui/ui |
onChange* | (isSelected: boolean) => void | — | — | @m3-ui/ui |
size | ButtonSize | undefined | — | — | @m3-ui/ui |
startIcon | ReactNode | — | — | @m3-ui/ui |
style | StyleOrFunction<ToggleButtonRenderProps> | undefined | — | — | @m3-ui/ui |
Inherited React / web props (101)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-controls | string | undefined | — | Identifies the element (or elements) whose contents or presence are controlled by the current element. | react-aria |
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-disabled | boolean | "true" | "false" | undefined | — | Indicates whether the element is disabled to users of assistive technology. | react-aria |
aria-expanded | boolean | "true" | "false" | undefined | — | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. | react-aria |
aria-haspopup | boolean | "true" | "false" | "dialog" | "grid" | "listbox" | "menu" | "tree" | undefined | — | Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. | react-aria |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
aria-pressed | boolean | "true" | "false" | "mixed" | undefined | — | Indicates the current "pressed" state of toggle buttons. | react-aria |
autoFocus | boolean | undefined | — | Whether the element should receive focus on render. | @react-types/shared |
children | ChildrenOrFunction<ToggleButtonRenderProps> | — | The children of the component. A function may be provided to alter the children based on component state. | react-aria-components |
className | ClassNameOrFunction<ToggleButtonRenderProps> | undefined | 'react-aria-ToggleButton' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
defaultSelected | boolean | undefined | — | Whether the element should be selected (uncontrolled). | react-aria |
dir | string | undefined | — | — | @react-types/shared |
excludeFromTabOrder | boolean | undefined | — | Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available. | @react-types/shared |
hidden | boolean | undefined | — | — | @react-types/shared |
id | Key | undefined | — | When used in a ToggleButtonGroup, an identifier for the item in `selectedKeys`. When used standalone, a DOM id. | react-aria-components |
inert | boolean | undefined | — | — | @react-types/shared |
isDisabled | boolean | undefined | — | Whether the button is disabled. | react-aria |
lang | string | undefined | — | — | @react-types/shared |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onBlur | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. | @react-types/shared |
onClick | ((e: MouseEvent<FocusableElement>) => void) | undefined | — | **Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress` provided for compatibility with other libraries. `onPress` provides additional event details for non-mouse interactions. | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onFocus | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. | @react-types/shared |
onFocusChange | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onHoverChange | ((isHovering: boolean) => void) | undefined | — | Handler that is called when the hover state changes. | @react-types/shared |
onHoverEnd | ((e: HoverEvent) => void) | undefined | — | Handler that is called when a hover interaction ends. | @react-types/shared |
onHoverStart | ((e: HoverEvent) => void) | undefined | — | Handler that is called when a hover interaction starts. | @react-types/shared |
onKeyDown | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is pressed. | @react-types/shared |
onKeyUp | ((e: KeyboardEvent) => void) | undefined | — | Handler that is called when a key is released. | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPress | ((e: PressEvent) => void) | undefined | — | Handler that is called when the press is released over the target. | @react-types/shared |
onPressChange | ((isPressed: boolean) => void) | undefined | — | Handler that is called when the press state changes. | @react-types/shared |
onPressEnd | ((e: PressEvent) => void) | undefined | — | Handler that is called when a press interaction ends, either over the target or when the pointer leaves the target. | @react-types/shared |
onPressStart | ((e: PressEvent) => void) | undefined | — | Handler that is called when a press interaction starts. | @react-types/shared |
onPressUp | ((e: PressEvent) => void) | undefined | — | Handler that is called when a press is released over the target, regardless of whether it started on the target or not. | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
preventFocusOnPress | boolean | undefined | — | Whether to prevent focus from moving to the button when pressing it. Caution, this can make the button inaccessible and should only be used when alternative keyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's increment/decrement control. | react-aria |
render | DOMRenderFunction<"button", ToggleButtonRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
Source: packages/ui/src/components/ToggleButton/ToggleButton.tsx:95
Material fidelity and web adaptation
- Family
- Toggle buttons
- Provenance
- compose: Compose Material3 contract · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- ToggleButton · ElevatedToggleButton · FilledTonalToggleButton · OutlinedToggleButton
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implements filled, elevated, filled-tonal, and outlined controlled toggle buttons with selected/unselected Material state, optional start icon, disabled treatment, expressive size buckets, token-backed shape/elevation/color transitions, and reduced-motion support.
- Behavior fidelity
- adapted: React Aria ToggleButton owns native button interaction and exposes the controlled selected state with aria-pressed. This intentionally differs from Compose checkbox-role semantics while preserving the browser-native pressable-toggle model, keyboard activation, focus behavior, and disabled state.
- Semantics fidelity
- adapted: React Aria ToggleButton owns native button interaction and exposes the controlled selected state with aria-pressed. This intentionally differs from Compose checkbox-role semantics while preserving the browser-native pressable-toggle model, keyboard activation, focus behavior, and disabled state.
- Adaptations
- React Aria ToggleButton owns native button interaction and exposes the controlled selected state with aria-pressed. This intentionally differs from Compose checkbox-role semantics while preserving the browser-native pressable-toggle model, keyboard activation, focus behavior, and disabled state.
Material defines the visual/selection intent. React Aria button + aria-pressed semantics are the deliberate web adaptation; CSS rounded geometry is the web projection of the audited Material shape contract rather than an arbitrary path-shape API.
Related components
- Button — momentary actions.
- Icon button — compact icon toggles.
- Button group — grouped or connected actions/selections.