Component

Button Group

Groups related buttons with shared, touching edges. Pass items with value and onValueChange, or defaultValue, for a real single-selection control.

Single selection

With items and a value the group becomes a radiogroup: the selected item takes the group's contained color, and arrow keys move the selection.

Selected: week

defaultValue sets the starting selection and the group keeps its own state from there. An item whose label is only an icon takes its own aria-label.

size sets the height of every button in the group - sm, md (the default), or lg - matching Button at the same value.

An item with disabled stays visible but cannot be selected, and the arrow keys skip over it.

The group is one tab stop: Tab lands on the selected item, and Left/Right (Up/Down when vertical) move and select, wrapping at either end
Name the group with aria-label so the radiogroup is announced with a purpose

Prop	Type	Default	Description
defaultValue	string	None	Initially selected value (single-selection mode, uncontrolled).
items	ButtonGroupItem[]	None	Enables single-selection mode. Omit to use ButtonGroup purely as a visual grouping wrapper around `Button` children.
onValueChange	((value: string) => void)	None	Called with the newly selected value (single-selection mode).
orientation	"horizontal" \| "vertical"	"horizontal"	Lays the buttons out in a row or a column, joining the adjacent corners.
size	ComponentSize	"md"	Height of every button in the group.
tone	ComponentTone	"default"	Contained color used by the selected item. Default "default".
value	string	None	Controlled selected value (single-selection mode).

defaultValueNone

string

Initially selected value (single-selection mode, uncontrolled).

itemsNone

ButtonGroupItem[]

Enables single-selection mode. Omit to use ButtonGroup purely as a visual grouping wrapper around `Button` children.

onValueChangeNone

((value: string) => void)

Called with the newly selected value (single-selection mode).

orientation"horizontal"

"horizontal" | "vertical"

Lays the buttons out in a row or a column, joining the adjacent corners.

size"md"

ComponentSize

Height of every button in the group.

tone"default"

ComponentTone

Contained color used by the selected item. Default "default".

valueNone

string

Controlled selected value (single-selection mode).

Also accepts everything from Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">.

Coding agents read this reference, with its examples, from the version your project has installed, through the Fuji UI MCP server. Set up your agent