ki-button-group
@kimen/elements/ki-button-group- Source
- Agent reference
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.
<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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
attached | attached | boolean | false | Joins 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. |
label | label | string | – | Required accessible name for the group or toolbar (for example, "Text formatting"). Provide a localized name that describes the actions' shared purpose. |
size | size | "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. |
toolbar | toolbar | boolean | false | Gives the group toolbar semantics, a framed surface and one Tab stop. Horizontal arrows, Home and End move between the toolbar's actions. |
Slots
| Slot | Description |
|---|---|
| (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
| Part | Description |
|---|---|
group | The 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.
| Token | Description |
|---|---|
--ki-button-group-attached-gap | Gap between joined actions. |
--ki-button-group-attached-radius | Radius of the logical corners along a shared button edge. |
--ki-button-group-backdrop-filter | Complete optional backdrop filter for the toolbar surface. |
--ki-button-group-bg | Toolbar surface colour. |
--ki-button-group-bg-image | Optional decorative image over the toolbar surface. |
--ki-button-group-border-color | Thin toolbar frame colour. |
--ki-button-group-border-width | Thickness of the toolbar frame and divider. |
--ki-button-group-divider | Decorative toolbar separator ink. |
--ki-button-group-divider-size | Block size of a vertical toolbar separator. |
--ki-button-group-fg | Default toolbar foreground on its raised surface. |
--ki-button-group-gap | Gap between actions in a spaced group. |
--ki-button-group-padding | Toolbar frame inset and divider margin. |
--ki-button-group-radius | Logical outside radius of the toolbar frame. |
--ki-button-group-seam-overlap | Shared-edge overlap between adjacent attached actions. |
--ki-button-group-toolbar-gap | Gap between toolbar actions. |
--ki-typography-family-body | semantic font family for typography family body. |