Skip to content
Kimenpre-v1documentation home
Color scheme

ki-button-group

Group related actions such as Undo and Redo or text formatting. Use a segmented control for a single-choice setting and links for navigation.

Spaced and attached groups

Give the group a label that describes the actions together. Add attached to join the buttons at their inner edges. An attached group takes the first button’s variant and size. Set size on the group to give every button that size in any mode.

Theme for this example
Color scheme for this example
Undo Redo Copy Paste
<ki-button-group label="History">
<ki-button type="button">Undo</ki-button>
<ki-button type="button">Redo</ki-button>
</ki-button-group>
<ki-button-group label="Clipboard" attached>
<ki-button type="button">Copy</ki-button>
<ki-button type="button">Paste</ki-button>
</ki-button-group>

Use type="button" for actions inside a form that should leave the form alone.

Keyboard toolbar

Tab enters the toolbar at its first available action, then returns to the most recently focused action on later visits. Left and right arrows follow the visual order in both writing directions. Home and End reach the first and last available actions. Tab and Shift+Tab leave the toolbar.

Wrap each icon button in a tooltip with the same label. Keep that label stable on toggles and update pressed with the application state. The button exposes it as aria-pressed. A vertical separator can distinguish sets of actions within the toolbar.

import '@kimen/elements/icons/bold';
import '@kimen/elements/icons/italic';
<ki-button-group label="Formatting" toolbar size="sm">
<ki-tooltip label="Bold">
<ki-icon-button label="Bold" variant="ghost" pressed="true">
<ki-icon name="bold"></ki-icon>
</ki-icon-button>
</ki-tooltip>
<ki-tooltip label="Italic">
<ki-icon-button label="Italic" variant="ghost" pressed="false">
<ki-icon name="italic"></ki-icon>
</ki-icon-button>
</ki-tooltip>
<span role="separator" aria-orientation="vertical"></span>
<ki-button type="button" variant="ghost">Clear formatting</ki-button>
</ki-button-group>

Split button

Use an attached text button for the primary action and a labeled chevron button to open the alternatives. When ki-menu is available in your build, set its anchor to the chevron button’s ID. The application handles the primary click and the menu selection independently. Set the icon button’s expanded property to the popup’s current open state.

Theme overrides

--ki-button-group-gap controls spacing between ordinary buttons. --ki-button-group-divider controls the ink of vertical toolbar separators. Use a surrounding data-ki-density="touch" region when the layout needs larger targets.

API reference

When to use: place two to five related actions together, present a primary action with a menu of alternatives, or give formatting tools one Tab stop.

When not to use: for a single-choice setting, unrelated actions, or navigation. Use a segmented control for a single-choice setting and links for navigation.

Properties & attributes

AttributePropertyTypeDefaultDescription
attachedattachedbooleanfalseJoins neighboring actions at their inner edges. Buttons share the first button's variant and use its size when the group has no explicit size. Use for a closely related set of actions or for a split button.
labellabelstring–Required accessible name for the group or toolbar (for example, "Text formatting"). Provide a localized name that describes the actions' shared purpose.
sizesize"lg" | "md" | "sm" | "xl" | "xs" | undefined–Applies one token-backed size to each button while it belongs to the group. Omit it to keep individual sizes in spaced mode.
toolbartoolbarbooleanfalseGives the group toolbar semantics, a framed surface and one Tab stop. Horizontal arrows, Home and End move between the toolbar's actions.

Slots

SlotDescription
(default)Related ki-button and ki-icon-button controls, in reading order. Wrap labeled icon actions in ki-tooltip with the same label to show the label on focus and hover. A toolbar can also include vertical separators.

CSS parts

PartDescription
groupThe named group or toolbar surface.

CSS custom properties

The public styling contract of ki-button-group: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-button-group-attached-gapGap between joined actions.
--ki-button-group-attached-radiusRadius of the logical corners along a shared button edge.
--ki-button-group-backdrop-filterComplete optional backdrop filter for the toolbar surface.
--ki-button-group-bgToolbar surface colour.
--ki-button-group-bg-imageOptional decorative image over the toolbar surface.
--ki-button-group-border-colorThin toolbar frame colour.
--ki-button-group-border-widthThickness of the toolbar frame and divider.
--ki-button-group-dividerDecorative toolbar separator ink.
--ki-button-group-divider-sizeBlock size of a vertical toolbar separator.
--ki-button-group-fgDefault toolbar foreground on its raised surface.
--ki-button-group-gapGap between actions in a spaced group.
--ki-button-group-paddingToolbar frame inset and divider margin.
--ki-button-group-radiusLogical outside radius of the toolbar frame.
--ki-button-group-seam-overlapShared-edge overlap between adjacent attached actions.
--ki-button-group-toolbar-gapGap between toolbar actions.
--ki-typography-family-bodysemantic font family for typography family body.

Try the toolbar and split button appearance in Storybook