Toggle Button — HeroGPUI

Usage

Live example

Rust

1use herogpui::prelude::{ToggleButton, ToggleButtonGroup};
2
3ToggleButton::new("toggle-button")
4    .label("Bold")

Live HeroGPUI compiled to WebAssembly. Select any example without loading another WASM instance.

Anatomy

Rust types

ToggleButtonToggleButtonGroup

Toggle Button is assembled from these builders. The API reference lists each one.

Customization

Appearance builders and theme tokens Toggle Button uses.

Styling

Toggle Button styling
Style	Description
`flex + h(36px) + gap(px(8.)) + px(16.) + control_radius`	Base toggle geometry, typography and rounded control surface.
`no .border_1()`	The toggle has no border; selected state uses a fill and focus uses a ring.
`ToggleVariant::Default/Ghost + colors.default`	Default unselected tokens, with the ghost variant supplying transparent background.
`is_selected + colors.accent.soft/soft_foreground/soft_hover`	Selected toggles use the accent-soft palette rather than the solid accent fill.
`ToggleVariant::Default`	Filled default variant token overrides.
`ToggleVariant::Ghost`	Low-emphasis ghost variant token overrides.
`Size::Sm + PRESSED_SCALE_SUBTLE`	Small desktop metrics and the subtle size-specific press scale.
`Size::Md + PRESSED_SCALE`	Medium is the base size and uses the standard press scale.
`Size::Lg + PRESSED_SCALE_FIRM`	Large desktop height, typography, default horizontal padding and firm press scale.
`is_icon_only + width(height)`	Square medium icon-only control.
`is_icon_only + size-specific height`	Small and large icon-only square sizes.
`child(element)`	Built-in SVG icon sizing and alignment; arbitrary child elements are accepted by without this selector-specific treatment.
`anim::pressed + immediate hover/background`	Transitions press geometry and color; applies the geometry in one frame and does not interpolate the color or press ramp.
`flex + items_center + justify_center + gap(px(0.))`	Connected group container.
`orientation(SelectionOrientation)`	Orientation-controlled group axis.
`full_width(true) + slot.flex_1`	Full-width group and equal-width member slots.
`group_edge + group_radius_any`	Attached members merge into one control while retaining the group perimeter radius.
`if !is_grouped { anim::pressed(...) }`	Attached members suppress their individual press scale.
`ring_if_focused(offset = false)`	Removes the offset seam but cannot draw GPUI's shadow ring inset.
`absolute + foreground.alpha(0.15) + hairline_radius`	Uses a fixed foreground-derived color rather than each member's currentColor.
`separator slot geometry in ToggleButtonGroup::render`	Orientation-specific divider geometry.
`static separator div`	Fades separator opacity; draws the correct static geometry without that transition.
`is_detached(true) + gap(px(4.)) + GroupEdge::Only`	Detached groups separate members, restore full radii and hide dividers.

API reference

Builders

Toggle Button builders
Builder	Type	Default	Description
`variant(ToggleVariant)`	`ToggleVariant`	`ToggleVariant::Default`	Visual style variant
`size(Size)`	`Size`	`Size::Md`	Size of the toggle button
`is_icon_only(bool)`	`bool`	`false`	Whether the button contains only an icon
`is_selected(bool)`	`bool`	—	Controlled selected state
`default_selected(bool)`	`bool`	`false`	Default selected state (uncontrolled)
`is_disabled(bool)`	`bool`	`false`	Whether the toggle button is disabled
`on_change(callback)`	`Fn(isSelected: bool) -> ()`	—	Handler called when selection changes
`on_press(event)`	`event`	—	Handler called when the button is pressed
`label(value) / content(render) / child(element)`	`AnyElement \| Fn(values: ToggleButtonRenderProps) -> AnyElement`	—	Button content or render prop
`content(render)`	`bool`	—	Whether the button is currently selected
`selection_mode(SelectionMode)`	`SelectionMode`	`SelectionMode::Single`	Whether one or multiple buttons can be selected
`selected_keys(keys)`	`iterable of keys`	—	Controlled selection state; accepts SharedString keys only.
`default_selected_keys(keys)`	`iterable of keys`	—	Default selected keys (uncontrolled); accepts SharedString keys only.
`on_selection_change(callback)`	`Fn(keys: Set<Key>) -> ()`	—	Called when selection changes; reports SharedString keys only.
`disallow_empty_selection(bool)`	`bool`	`false`	Prevents clearing all selections
`orientation(SelectionOrientation)`	`SelectionOrientation`	`SelectionOrientation::Horizontal`	Layout direction
`is_detached(bool)`	`bool`	`false`	Whether buttons are visually separated with gaps
`full_width(bool)`	`bool`	`false`	Whether the group fills available width

Parts

Toggle Button parts
Part	Description
`ToggleButton`	Focusable toggle root that owns selected, press and disabled state.
`ToggleButtonGroup`	Selection and layout root; separators are explicit composition requested with separators(true).
`ToggleButtonGroup`	Optional explicit divider composition; uses separators(true), and custom style is unavailable.

States

Toggle Button states
Builder	State	Description
`is_selected + colors.accent.soft()`	`Selected`	Accent-soft background and foreground show the selected state.
`hover + InteractiveState::is_hovered`	`Hovered`	Variant-specific hover background, including selected accent-soft-hover.
`anim::pressed + InteractiveState::is_pressed`	`Pressed`	Pressed feedback applies the size-specific scale and pressed background.
`tab_stop_handle + ring_if_focused`	`Focus visible`	Keyboard focus shows the status-focused ring.
`is_disabled + disabled_opacity`	`Disabled`	Disabled toggles are dimmed, inert and removed from the tab order.
`selected_keys(keys) + util::controlled`	`Controlled selection`	The caller owns the selected key set and receives selection callbacks.
`default_selected_keys(keys) + util::controlled`	`Uncontrolled selection`	The group owns its selected key set after the initial seed.
`selection_mode(SelectionMode::Single)`	`Single selection`	Selecting a member replaces the previous selection.
`selection_mode(SelectionMode::Multiple)`	`Multiple selection`	Members can be selected independently.
`disallow_empty_selection(bool)`	`Disallow empty selection`	The last selected member cannot be cleared in single-selection mode.
`orientation(SelectionOrientation::Horizontal)`	`Horizontal group`	Members flow along the horizontal axis.
`orientation(SelectionOrientation::Vertical)`	`Vertical group`	Members stack along the vertical axis.
`full_width(true) + child slots flex_1`	`Full width group`	The group fills its parent and stretches each member.
`group_edge + group_radius_any`	`Attached group`	Adjacent members share an edge and keep only the outer corners rounded.
`is_detached(true)`	`Detached group`	Members regain full radii and are separated by a 4px gap.
`is_grouped gates anim::pressed`	`Group pressed`	Attached members do not scale and therefore cannot open gaps at the seam.
`ring_if_focused(offset = false)`	`Group focus visible`	Removes the outer offset but GPUI has no inset box-shadow equivalent.

Button Button Group Close Button