BtnToggle
Single or multi-select toggle group of Btn elements. Wraps OrigamBtnGroup and adds selection state via useGroup (supports v-model).
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<origam-btn-toggle> — outer toggle shell ① (adds .origam-btn-toggle modifier), inner <origam-btn-group> ② rendering child buttons ③. Selected button receives active state from useGroup.- 1.origam-btn-toggle
- Root modifier class added on top of
.origam-btn-group. OrigamBtnToggle is a thin wrapper that adds selection state (useGroup) and exposes the group navigation API (next/prev/select). - 2.origam-btn-group
- The proxied
<origam-btn-group>with all group-level props forwarded via filterProps. Provides the visual container (border, elevation, rounded, overflow: hidden). - 3(origam-btn children)
- Child
<origam-btn>elements with avalueprop. isSelected state from useGroup drives the active styling on the matching button.
API
Props
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.
- dividedbooleanfalse
- Inherited from BtnGroup. Shows a thin border between adjacent buttons.
- itemsArray<IBtnProps>[]
- Array of IBtnProps objects to render toggle buttons programmatically.
- tagstring'div'
- HTML element rendered at the root (proxied to OrigamBtnGroup).
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- Border-radius for the group container.
- 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 toggle group.
- 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
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- Density propagated to child buttons via OrigamBtnGroup defaults.
- elevationTElevation
- Box-shadow elevation for the group container.
- color
- Foreground color propagated to all child buttons.
- bgColor
- Background color propagated to all child buttons.
- 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
- hoverClassstring
- activeboolean | IStateEffectConfig
- activeClassstring
- variantTVariant
- sizeTSize | number
- disabledboolean
- modelValueany
- Currently selected value(s). Single value in single-select mode; array in multiple mode. Binds with v-model.
- multiplebooleanfalse
- Allows selecting multiple buttons simultaneously. modelValue becomes an array.
- mandatorybooleanfalse
- Keeps at least one item selected at all times. "force" also prevents deselecting the last item even programmatically.
- maxnumber
- Maximum number of simultaneously selected items (multiple mode only).
- selectedClassstring
API
Slots
Emplacements de contenu exposés par ce composant.
- #default
- Content area. Receives the group selection API (isSelected, next, prev, select, selected). OrigamBtn children with a value prop participate in selection automatically.
- #item
- Override rendering of each item from the items array. Receives the IBtnProps object and its index.
API
Emits
Événements émis par ce composant.
- @update:modelValueany
- Fired when the selection changes. Payload is the new selected value (single mode) or array of selected values (multiple mode).
API
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- () => void
- Selects the next button in the group (wraps around).
- () => void
- Selects the previous button in the group (wraps around).
- (id: string | number, value: boolean) => void
- Programmatically select or deselect a button by its value id.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to child components.
- Ref<string>
- Reactive CSS string generated by useStyle from the computed btnToggleStyles.
- 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.
- Inherited from BtnGroup. Border-radius of the toggle container.
- Inherited from BtnGroup. Density offset for min-height.
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 toggle button. |
| Enter / Space | Toggles the selection state of the focused button. |
Notes
- Inherits role="group" from OrigamBtnGroup. Add aria-label to describe the toggle purpose (e.g. "Text alignment controls").
- Each selected child OrigamBtn should communicate its state via aria-pressed="true". Ensure child buttons pass their active state correctly.
- When mandatory=true, at least one button is always selected. Consider communicating this constraint to assistive technology users via group description.
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 toggle container.
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.
Single-select toggle
Multi-select toggle
From items array
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.