BtnGroup
Groups Btn elements into a connected segmented control. Propagates density, color and hover/active state to child buttons via OrigamDefaultsProvider.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-btn-group> — root container ① (role="group"), OrigamDefaultsProvider ② wrapping child buttons ③. With divided, a border-inline-end separates adjacent buttons.- 1.origam-btn-group
- Root element (default:
<div>, role="group"). inline-flex, overflow: hidden, vertical-align: middle. Carries border, elevation and rounding classes. Child buttons are forced border-radius: 0 and box-shadow: none via :deep. - 2.origam-btn-group--divided
- Modifier applied when
divided=true. Adds aborder-inline-endbetween non-last child buttons. - 3(origam-btn children)
- Child
<origam-btn>elements. Receive density, color, bgColor, hover, active defaults from the group via OrigamDefaultsProvider. Individual children can override these defaults.
API
Props
All props accepted by this component, with their type, default value and description.
- dividedbooleanfalse
- Shows a thin border between adjacent buttons (border-inline-end on each non-last child).
- itemsArray<IBtnProps>[]
- Array of props objects to render OrigamBtn instances programmatically. Ignored when the default slot is used.
- tagstring'div'
- HTML element rendered at the root. Carries role="group" for accessibility.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- Border-radius token for the group container. Child buttons are forced border-radius: 0 via :deep so only the group corners are rounded (overflow: hidden clips the rest).
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border around the entire group container.
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- Override border color for the group container.
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- Density propagated to all child buttons via OrigamDefaultsProvider. Affects group min-height.
- elevationTElevation
- Box-shadow elevation for the group container. Child buttons have box-shadow: none forced via :deep.
- color
- Foreground color propagated to all child buttons as a default.
- bgColor
- Background color propagated to all child buttons as a default.
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- hoverboolean | IStateEffectConfig
- Hover state override propagated to child buttons via OrigamDefaultsProvider.
- hoverClassstring
- activeboolean | IStateEffectConfigfalse
- Active state override propagated to child buttons via OrigamDefaultsProvider.
- activeClassstring
- variantTVariant
- sizeTSize | number
API
Slots
Content slots exposed by this component.
- #default
- Content area for OrigamBtn (or BtnToggle) children. When provided, the items prop is ignored.
- #item
- Override rendering of each item from the items array. Receives the IBtnProps object and its index.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to child components. Used by OrigamBtnToggle to proxy group props.
- Ref<string>
- Reactive CSS string generated by useStyle from the computed btnGroupStyles.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet into the document.
- () => void
- Removes the injected style sheet.
- Ref<boolean>
- True once the style sheet has been injected into the DOM.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Reference height used to compute min-height with density offset.
- Density offset. comfortable: +8px, default: 0px, compact: −8px.
- Group container border-radius. Overridden by rounded modifier classes.
- Group border width. Set to "thin" when border=true.
- Group border style.
- Group border color (currentColor by default).
- Group background color.
- Group foreground color (inherited by default).
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| Tab | Moves focus through each button in the group sequentially. |
| Enter / Space | Activates the focused button. |
Notes
- The root element always carries role="group". Consider adding aria-label or aria-labelledby to describe the group purpose (e.g. "Text alignment").
- Child buttons inside the group share adjacent borders (border-inline-end suppressed on non-last, border-inline-start on non-first). This ensures no double borders visually while keeping each button individually focusable.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- dimensionvar(--origam-radius---sm)
- Default border radius for the group container.
- dimensionvar(--origam-border__width---0)
- Default border width (none until border prop is set).
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic group
Divided group
From items array
Ecosystem
Family
Components from the same folder that share conventions and often compose together.