BtnGroup
Groups Btn elements into a connected segmented control. Propagates density, color and hover/active state to child buttons via OrigamDefaultsProvider.
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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
Emplacements de contenu exposés par ce composant.
- #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
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- <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.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- 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
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Rôles ARIA
Interactions clavier
| Touche | 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.
Fondation
Design tokens
Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.
- 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).
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic group
Divided group
From items array
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.