ToggleTextButton
Labeled two-state toggle — visible text, optional addon and pressed variant, alone or inside ToggleGroup.
Base UI
ToggleTextButton is the labeled two-state control. Visible text (children) names the option; an optional Button-family addon can sit beside it. Pressed state stays on until toggled off — same interaction model as ToggleButton, but Button chrome instead of icon-only.
variant defaults to flat at rest; pass pressedVariant when the on state should read clearly in quiet chrome. Reach for ToggleButton when the control is glyph-only and needs restingIcon / pressedIcon. Reach for Button when the click commits once and does not stay pressed. Reach for Tabs when options switch whole content panels with tab semantics — not a small exclusive strip of labels.
When related toggles share one selection model, wrap them in ToggleGroup. Each child needs a distinct value; visible text (or an accessible name on icon-only siblings) labels the option. The group root takes value / defaultValue / onValueChange as string[], and multiple when several can stay on. Label the group with aria-label or aria-labelledby.
When to use
- Toolbar or filter options with a readable text label (Bold, Grid, Sync)
- Exclusive labeled choices that stay pressed (billing period, view mode) without Tabs panels
- Related labeled toggles that share one selection model (
ToggleGroup), alone or mixed with ToggleButton
When not to use
- Icon-only chrome with no visible label → ToggleButton
- A one-shot labeled commit (Save, Delete) → Button
- A settings boolean that should look like a switch → Switch
- Tabbed panel navigation with tab semantics → Tabs
Related
- ToggleButton — icon-only pressed toggles and groups
- Button — labeled commits without a pressed state
- Switch — labeled on/off settings
- Tabs — switching content panels
Common examples
Pressed variant
Default resting chrome is flat. Pass pressedVariant so the on state looks filled or secondary in a quiet toolbar. The visible label stays in both states.
Addon
addon accepts a leading or trailing glyph the same way Button does. The label still carries the name; the glyph is supporting chrome.
Controlled press
Drive pressed and onPressedChange when the product owns the state — persist a preference, update sibling copy, or fire analytics when the toggle flips.
In a group
ToggleGroup coordinates exclusive (or multi) pressed values across labeled children. Give each child a value; wrap the group in a Surface when you want a bordered toolbar shell.
Mixed group
The same ToggleGroup can hold ToggleTextButton and ToggleButton children. Text options keep visible labels; icon-only siblings still need aria-label (or aria-labelledby).
Exclusive options
For a small exclusive strip that swaps nearby content (billing period, view mode), keep ToggleGroup single-select and update the price (and any sibling copy) when selection changes. Point the group at that region with aria-controls and give the region an id plus a polite live region so the change is announced. Prefer Tabs when the UI is a full tablist with panels.
Ask your agent
Add a formatting strip with Bold, Italic, and Notify as labeled toggles. One choice at a time. Put it in a quiet bordered surface and label the group for screen readers.Last updated on