Button Group

Grouped controls for adjacent actions and toolbar layouts.

Review the latest project changes before sharing them with your team.

Installation

npx shadcn@latest add @iconiq/button-group

ReducedMotion

Pass reducedMotionwhen you want the installed component to settle into its quieter motion path immediately. Leaving the prop unset still respects the user's system-level reduced motion preference.

Review the latest project changes before sharing them with your team.

Props

Button

5 props

Compact bordered action button with muted idle text, darker hover text, optional ripple feedback, and shadcn-style size controls.

childrenReactNode

Required

Button content rendered inside an inline span so icon-and-label pairs keep consistent spacing across sizes.

classNamestring

Merged onto the root button. Use it for local width, spacing, or surface overrides.

size"sm" | "md" | "lg"

Default"md"

Compacts or expands the control while keeping the same toolbar-style border and hover treatment.

disableRippleboolean

Defaultfalse

Turns off the click ripple while preserving the rest of the hover and focus styling.

showBorderboolean

Defaulttrue

Removes the outer border when set to false, which is useful for quieter toolbar-style actions.

Notes

Most standard button props such as type, disabled, onClick, name, value, aria-*, and data-* are forwarded to the underlying motion button.

The public prop surface intentionally leaves out the native drag and CSS animation callback props because they conflict with Motion's own handler names.

IconButton

5 props

Icon-only toolbar action that shares the same compact border, muted idle tone, and optional ripple behavior as Button.

childrenReactNode

Required

Icon content rendered inside the inline content span. SVG children inherit the built-in size utilities for the active size variant.

classNamestring

Merged onto the icon button root for size or surface overrides.

size"sm" | "md" | "lg"

Default"md"

Controls the square footprint of the icon button without changing its general look and feel.

disableRippleboolean

Defaultfalse

Disables the click ripple for quieter toolbar actions.

showBorderboolean

Defaulttrue

Removes the outer border when set to false so the icon action can sit more quietly beside a borderless group.

ButtonGroup

3 props

Slot-aware flex wrapper for arranging adjacent controls with horizontal or vertical rounding rules.

childrenReactNode

Required

Buttons, icon buttons, ButtonGroupText, ButtonGroupSeparator, ButtonGroupItems, or any other data-slot controls you want to keep together.

orientation"horizontal" | "vertical"

Default"horizontal"

Chooses the grouped rounding and shared-border direction used by buttonGroupVariants.

classNamestring

Merged onto the outer group. Use it for wrapping, alignment, or local spacing overrides.

ButtonGroupText

3 props

Non-interactive text segment for labeling a group without leaving the shared button-group surface.

childrenReactNode

Required

Short label or inline content rendered inside the grouped text segment.

renderuseRender render prop

Optional Base UI render override when you need a different element while keeping the same merged props.

classNamestring

Merged with the default muted bordered text segment classes.

ButtonGroupSeparator

2 props

Separator segment for splitting labels, buttons, inputs, and grouped actions inside ButtonGroup.

orientation"horizontal" | "vertical"

Default"vertical"

Controls the separator axis. Vertical separators are the default for horizontal button groups.

classNamestring

Merged with the self-stretching separator classes for custom color or spacing.

ButtonGroupItems

5 props

Segmented button shell that converts valid child elements into compact internal buttons with muted idle text and darker hover states.

childrenReactNode

Required

Pass plain button-like elements as children. Their props and children are hoisted into the internal motion buttons rendered by the group.

classNamestring

Merged onto the outer segmented wrapper for width or surface overrides.

size"sm" | "md" | "lg"

Default"md"

Sets the shared height, padding, and typography of the grouped buttons.

showDividersboolean

Defaulttrue

Removes the internal separator lines and the outer wrapper border when set to false, then switches the group to a smoother shared hover surface.

disableRippleboolean

Defaultfalse

Turns off the ripple for every internal button rendered by the group.

Notes

Only valid React elements are rendered. Non-element children are ignored.

The child node itself is not preserved; ButtonGroupItems reads each child's props and children, then renders a fresh motion button for that slot.

When showDividers is false, hover feedback moves as a shared spring layer between items instead of flashing independently on each button.

SegmentedControl

6 props

String-based segmented selector with compact sizing, keyboard support, muted idle labels, and a spring-driven selected indicator.

optionsstring[]

Required

Ordered list of visible segments. The first option becomes the uncontrolled initial selection when value is not provided.

valuestring

Controlled selected option. When provided, the internal state syncs to this prop through an effect.

onChange(value: string) => void

Called with the selected option whenever a segment is pressed.

classNamestring

Merged onto the segmented wrapper for width, alignment, or spacing overrides.

layoutIdstring

Default"segmented-indicator"

Motion layout id used by the selected indicator. Override it when you render multiple segmented controls on the same page and want isolated indicator motion.

size"sm" | "md" | "lg"

Default"md"

Controls the overall density of the segmented control shell and each segment inside it.

Notes

The control uses radiogroup semantics with arrow-key, Home, and End navigation.

Reduced-motion users keep the same state changes without the spring transitions.

ReducedMotion

1 prop

Shared motion override for the motion-enabled exports documented on this page.

reducedMotionboolean

When true, the component uses its calmer motion path immediately. Leaving it unset still respects the user's system-level reduced motion preference.

Notes

This prop can force reduced motion on, but it does not opt out of OS-level accessibility preferences when the system is already requesting less motion.