iconiq
—Open GitHub

Toggle Group

Segmented toggle group for switching one or more related states at once.

Installation

npx shadcn@latest add @iconiq/r-togglegroup

Props

ToggleGroupItem

5 props

Each toggle is described by a plain object so both provider-backed installs keep the same display and selection contract.
valuestring
Required
Stable identifier used for selection state and forwarded to the underlying toggle primitive item.
labelReactNode
Required
Visible item content rendered inside each segmented button. This can be plain text or richer inline content.
iconReactNode
Optional leading visual rendered before the label inside the button surface.
disabledboolean
Disables that item while keeping the rest of the group interactive.
ariaLabelstring
Accessible item name for icon-only buttons or abbreviated visual labels.

ToggleGroup

13 props

Segmented toggle group with the same Iconiq API layered over Radix UI primitives.
itemsToggleGroupItem[]
Required
Buttons to render in display order.
type"single" | "multiple"
Default"multiple"
Defaults to multiple selection. Pass type="single" for a one-of-many picker.
valuestring | string[]
Controlled selection state. Use a string for single mode or an array for multiple mode.
defaultValuestring | string[]
Initial selection state for uncontrolled usage, following the same single versus multiple shape as value.
onValueChange((value: string | undefined) => void) | ((value: string[]) => void)
Called with the next selected value in single mode or the next ordered selected values array in multiple mode.
size"default" | "sm"
Default"default"
Adjusts the item height, minimum width, and label sizing while keeping the same motion profile.
orientation"horizontal" | "vertical"
Default"horizontal"
Changes both the visual layout and the underlying keyboard navigation axis.
disabledboolean
Disables the whole group and prevents hover, tap, and selection changes.
classNamestring
Merged onto the segmented group shell for width, spacing, or placement overrides.
itemClassNamestring
Merged onto every toggle item so you can tune button sizing or local visual treatment without rewriting the structure.
reducedMotionboolean
Forces the quieter motion path while still respecting OS-level reduced motion preferences.
aria-labelstring
Accessible name for the group when no external label element is connected.
aria-labelledbystring
References external text that labels the whole group, which takes precedence over aria-label.

Notes

Current install target: Radix UI.
Dependencies declared by this registry entry: @radix-ui/react-toggle-group, motion.
Multiple mode is the default and starts with no items selected unless you pass defaultValue or a controlled value array.
Multiple mode normalizes outgoing values back into the original item order, so the callback shape stays stable even if users toggle items out of sequence.
Pass type="single" when only one item should stay pressed at a time. Single mode starts with no implicit selection unless you provide value or defaultValue.
Icon-only items should provide ariaLabel so every button still has a clear accessible name.
Installs a Radix UI toggle group with the same items, type, value, defaultValue, size, orientation, and reducedMotion API as the Base UI version.
Uses Radix toggle-group semantics underneath the same accent-fill toolbar styling as the Base UI version.