HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Button GroupView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorGroups related buttons into one control.StableSince 0.1.0ActionsUsageimport'@fusion.dev/helix/button-group'import'@fusion.dev/helix-headless/button-group'Preview
API ReferenceRoothelix-button-groupGroups related buttons into one control.
PropTypeDescriptiondisabledbooleanDefaultfalseDisables every button in the group, and says so on the group with
aria-disabled. Reflected, so a stylesheet can select on it.disallowEmptySelectionbooleanDefaultfalseKeeps at least one button pressed once one is, as React Aria's
disallowEmptySelection: a press that would leave none pressed is
refused.labelstringDefault""The group's name, read by screen readers.orientation"horizontal"|"vertical"Which way the buttons are stacked.selectionMode"multiple"|"single"Whether the buttons stay pressed: single keeps one pressed at a time and
multiple any number. Unset, they are action buttons, each its own tab
stop, as before.size"sm"|"md"|"lg"The size of every button in the group: their height, text, padding and
icons, from the density steps. Unset, the buttons take the size of the
region around the group.valuestringDefault""The values of the pressed buttons, comma separated, in a selection mode.
A button's own value names it, so a value holds no comma.valuesstring[]The pressed values as a list, in a selection mode, and an empty list
otherwise. Written, it presses exactly those buttons.variant"joined"|"spaced"Whether the buttons are one bar or a spaced row.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The buttons in the group.
EventTypeDescriptionchangeEventFired after a press changes value, in a selection mode.helix-before-changeHelixBeforeChangeEventFired before a press changes value, with the value it would leave in detail.value. Cancelable: call preventDefault() to keep the buttons as they are.
CSS PropertyDescription--button-group-gapSpace between the buttons, when spaced.--button-group-pressedWritten on the control inside each toggle button of a group with selection-mode: 1 while it is pressed and 0 while it is not. Read it in a ::part(button) rule to draw the pressed look.--button-group-pressed-background-colorFill behind a pressed button, in a selection mode. Defaults to the foreground color.--button-group-pressed-border-colorEdge of a pressed button, in a selection mode. Defaults to its fill.--button-group-pressed-colorWords and icons of a pressed button, in a selection mode. Defaults to the background color.
Custom stateDescriptionpressedWhile a group with selection-mode has a button pressed.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-button-groupGroups related buttons into one control.
PropTypeDescriptiondisabledbooleanDefaultfalseDisables every button in the group, and says so on the group with
aria-disabled. Reflected, so a stylesheet can select on it.disallowEmptySelectionbooleanDefaultfalseKeeps at least one button pressed once one is, as React Aria's
disallowEmptySelection: a press that would leave none pressed is
refused.labelstringDefault""The group's name, read by screen readers.orientation"horizontal"|"vertical"Which way the buttons are stacked.selectionMode"multiple"|"single"Whether the buttons stay pressed: single keeps one pressed at a time and
multiple any number. Unset, they are action buttons, each its own tab
stop, as before.valuestringDefault""The values of the pressed buttons, comma separated, in a selection mode.
A button's own value names it, so a value holds no comma.valuesstring[]The pressed values as a list, in a selection mode, and an empty list
otherwise. Written, it presses exactly those buttons.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The buttons in the group.
EventTypeDescriptionchangeEventFired after a press changes value, in a selection mode.helix-before-changeHelixBeforeChangeEventFired before a press changes value, with the value it would leave in detail.value. Cancelable: call preventDefault() to keep the buttons as they are.
CSS PropertyDescription--button-group-pressedWritten on the control inside each toggle button of a group with selection-mode: 1 while it is pressed and 0 while it is not. Read it in a ::part(button) rule to draw the pressed look.
Custom stateDescriptionpressedWhile a group with selection-mode has a button pressed.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionDisabledA group switched off as a whole with disabled, which disables every button in it.PreviewButtons joined into one control, sharing their edges.PreviewButtons joined into one control, sharing their edges.SelectionText styles that stay pressed, any number at once, set with selection-mode.SelectionText styles that stay pressed, any number at once, set with selection-mode.SpacedThree buttons in a group with space between them, set with variant.VerticalThe joined buttons stacked vertically, for a column too narrow for a row.VerticalThe joined buttons stacked vertically, for a column too narrow for a row.With IconsTwo buttons, each with an arrow icon beside its label.