BtnToggle
Single or multi-select toggle group of Btn elements. Wraps OrigamBtnGroup and adds selection state via useGroup (supports v-model).
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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
All props accepted by this component, with their type, default value and 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
Content slots exposed by this component.
- #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
Events emitted by this component.
- @update:modelValueany
- Fired when the selection changes. Payload is the new selected value (single mode) or array of selected values (multiple mode).
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- () => 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.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Inherited from BtnGroup. Border-radius of the toggle container.
- Inherited from BtnGroup. Density offset for min-height.
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 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.
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 toggle container.
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.
Single-select toggle
Multi-select toggle
From items array
Ecosystem
Family
Components from the same folder that share conventions and often compose together.