Skip to content

OrigamTabs ​

<OrigamTabs> is a fully-accessible tablist with optional content panels. It is composed of four siblings:

ComponentRole
<OrigamTabs>The tablist container. Owns the selection state via useGroup.
<OrigamTab>A single tab. Registers itself via useGroupItem. ARIA role="tab".
<OrigamTabPanels>The content area. Mirrors the same v-model as the tablist.
<OrigamTabPanel>A single content panel. ARIA role="tabpanel".

The two halves bind to the same v-model value — the tablist drives the selection, the panels render the matching content.

Basic usage ​

vue
<template>
    <OrigamTabs v-model="active">
        <OrigamTab :value="0">Profile</OrigamTab>
        <OrigamTab :value="1">Settings</OrigamTab>
        <OrigamTab :value="2">Billing</OrigamTab>
    </OrigamTabs>

    <OrigamTabPanels v-model="active">
        <OrigamTabPanel :value="0">Profile content.</OrigamTabPanel>
        <OrigamTabPanel :value="1">Settings content.</OrigamTabPanel>
        <OrigamTabPanel :value="2">Billing content.</OrigamTabPanel>
    </OrigamTabPanels>
</template>

<script setup lang="ts">
    import { ref } from 'vue'
    const active = ref<number>(0)
</script>

Variants ​

The visual treatment is controlled by the variant prop on <OrigamTabs>.

vue
<OrigamTabs v-model="active" variant="default" />
<OrigamTabs v-model="active" variant="pills" />
<OrigamTabs v-model="active" variant="underline" />
ValueDescription
defaultPlain row of buttons, separated by a subtle divider.
pillsEach tab is a rounded pill — active tab fills with the primary intent.
underlineActive tab gets a horizontal indicator bar.

Vertical orientation ​

Switch to a vertical column with direction="vertical". The indicator on variant="underline" moves to the trailing edge. ARIA aria-orientation follows the prop.

vue
<OrigamTabs v-model="active" direction="vertical" variant="underline">
    <OrigamTab :value="0">Inbox</OrigamTab>
    <OrigamTab :value="1">Sent</OrigamTab>
    <OrigamTab :value="2">Drafts</OrigamTab>
</OrigamTabs>

Lazy panels ​

By default, panel content is mounted on first activation and kept alive afterwards (v-show). Set eager on a specific panel to force it to mount from the start — useful when the panel must populate a form ref or trigger a fetch before being shown.

vue
<OrigamTabPanels v-model="active">
    <OrigamTabPanel :value="0" eager>Always mounted</OrigamTabPanel>
    <OrigamTabPanel :value="1">Lazy mounted</OrigamTabPanel>
</OrigamTabPanels>

Swipeable panels ​

On touch devices, enable horizontal swipe between panels with swipeable. Left swipe selects the next tab, right swipe the previous.

vue
<OrigamTabPanels v-model="active" swipeable>
    <OrigamTabPanel :value="0">…</OrigamTabPanel>
    <OrigamTabPanel :value="1">…</OrigamTabPanel>
</OrigamTabPanels>

Props ​

<OrigamTabs> ​

PropTypeDefaultDescription
modelValuenumber | string—Active tab value (two-way bound).
variant'default' | 'pills' | 'underline''default'Visual treatment.
direction'horizontal' | 'vertical''horizontal'Layout axis + ARIA orientation.
density'default' | 'compact' | 'comfortable''default'Vertical compression.
fixedbooleanfalseEach tab gets flex: 1 — equal width.
centeredbooleanfalseCenters the tablist in its container.
mandatorybooleantrueForbids the empty selection (ARIA-recommended).
disabledbooleanfalseDisables the entire tablist.
colorTIntent—Forwarded as a default to every child <OrigamTab>; does not paint the tablist itself. In the pills variant it sets the active tab's background and text (action.{intent}.bg / .fg); unset keeps action.primary. The --origam-tabs__item--pills--active---* tokens remain the fallback hook when no color is given.
bgColorTIntent | string—Paints the tablist surface. An intent resolves to --origam-color__{base}---bg and auto-pairs its contrast foreground; a raw CSS colour is emitted verbatim.
roundedTRounded—Corner-radius rung (IRoundedProps).
tagstring'div'Element rendered as the tablist root.
multiplebooleanfalseInherited from IGroupProps — allows several tabs to be selected at once.
maxnumber—Inherited from IGroupProps — caps the number of simultaneous selections when multiple.
selectedClassstring'origam-tab--active'Class applied to the selected <OrigamTab>.

<OrigamTab> ​

PropTypeDefaultDescription
valuenumber | string—Required. Identifier matched by the panel.
disabledbooleanfalseDisables this tab (skipped by keyboard).
selectedClassstring—Inherited from IGroupItemProps — per-tab override of the parent's selectedClass.
textstring''Text label, used when the default slot is not provided.
variant'default' | 'pills' | 'underline'—Visual treatment, normally mirrored down from the parent <OrigamTabs>.
tagstring'button'Element rendered as the tab root.
prependIconTIcon—Leading icon (IAdjacentProps — the same contract as OrigamBtn / OrigamChip / OrigamListItem).
appendIconTIcon—Trailing icon (badge, close, …).
prependAvatarstring—Leading avatar image, rendered by <OrigamAvatar> in the prepend slot.
appendAvatarstring—Trailing avatar image, rendered by <OrigamAvatar> in the append slot.
iconTIcon—Deprecated — use prependIcon. Same leading-icon position, kept for backward compatibility; ignored when prependIcon is set (resolvedPrependIcon = prependIcon ?? icon).
fontSizeTFontSize—Font size token override (xs · sm · md · lg · xl · …). Maps to --origam-tabs__item---font-size.
fontWeightTFontWeight—Font weight token override (regular · medium · semibold · bold · …). Maps to --origam-tabs__item---font-weight.
letterSpacingTLetterSpacing—Letter-spacing token override (tight · normal · wide · wider · widest). Maps to --origam-tabs__item---letter-spacing.
lineHeightTLineHeight—Line-height token override (none · tight · snug · normal · …). Maps to --origam-tabs__item---line-height (default none = 1).

<OrigamTabPanels> ​

PropTypeDefaultDescription
modelValuenumber | string—Active panel — same value as <OrigamTabs>.
transitionstring | false'fade'Transition name. false disables.
swipeablebooleanfalseAllow horizontal touch swipe between panels.
direction'horizontal' | 'vertical''horizontal'Layout axis, inherited from IDirectionProps.
tagstring'div'Element rendered as the panels container root.
mandatorybooleantrueInherited from IGroupProps — forbids the empty selection.
selectedClassstring'origam-tab-panel--active'Class applied to the active <OrigamTabPanel>.

<OrigamTabPanel> ​

PropTypeDefaultDescription
valuenumber | string—Required. Must match a sibling <OrigamTab>.
eagerbooleanfalseMount the panel content from the start instead of on first activation.
disabledbooleanfalseInherited from IGroupItemProps — excludes the panel from group selection.
selectedClassstring—Inherited from IGroupItemProps — class applied while this panel is the selected one.
tagstring'div'Element rendered as the panel root.

Events ​

ComponentEventPayload
<OrigamTabs>update:modelValuenew active value
<OrigamTabPanels>update:modelValuenew active value
<OrigamTab>group:selected{ value: boolean } — true when this tab becomes the selected one, false when it stops being it
<OrigamTabPanel>group:selected{ value: boolean } — same contract, on the panel side

group:selected is not optional chrome: both <OrigamTab> and <OrigamTabPanel> self-register through useGroupItem, which watches isSelected and calls vm.emit('group:selected', { value }) on the registering component's own instance. It fires on every selection change, whether or not a handler is bound — it is the per-item counterpart of the container's update:modelValue, and the only way to react to selection on the item itself rather than on the tablist.

vue
<template>
    <OrigamTabs v-model="tab">
        <OrigamTab value="one" text="One" @group:selected="onTabSelected" />
        <OrigamTab value="two" text="Two" @group:selected="onTabSelected" />
    </OrigamTabs>
</template>

<script setup lang="ts">
    function onTabSelected (payload: { value: boolean }) {
        // payload.value === true  → this tab just became active
        // payload.value === false → this tab just lost the selection
    }
</script>

Slots ​

ComponentSlotScopeDescription
<OrigamTabs>default{ isSelected, select, next, prev, selected, items }Children — usually <OrigamTab> instances.
<OrigamTab>default{ isSelected, toggle, select, value, disabled }Tab label. Falls back to the text prop.
<OrigamTabPanels>default{ isSelected, select, next, prev, selected, items }Children — usually <OrigamTabPanel> instances.
<OrigamTabPanel>default—Panel content.

Accessibility ​

<OrigamTabs> applies the ARIA tablist pattern out of the box:

  • <OrigamTabs> carries role="tablist" and aria-orientation matching direction.
  • Each <OrigamTab> carries role="tab", aria-selected, aria-controls (pointing to the matching panel), aria-disabled, and a managed tabindex so only the active tab participates in tab focus.
  • Each <OrigamTabPanel> carries role="tabpanel", aria-labelledby (pointing to the controlling tab), and tabindex="0" so the content is focusable for AT users.

Keyboard navigation (focus inside the tablist):

KeyAction
← / → (horizontal)Move focus and selection to previous / next tab.
↑ / ↓ (vertical)Move focus and selection to previous / next tab.
Home / EndMove focus and selection to first / last tab.
Enter / SpaceActivate the currently focused tab.

This is the WAI-ARIA APG "Tabs with Automatic Activation" pattern: the arrow keys move the focus, and selection follows it. That matters for screen readers — a selection change on a tab the user is not focused on is announced to nobody.

⚠️ Until #786 the arrows moved the selection but left the focus one step behind (measured in Chromium: aria-selected → tab 1 while document.activeElement stayed on tab 0). Home / End were always correct. The cause: the handler re-read the selection from the model right after writing it, and under a v-model that read still returns the previous id. Pinned by packages/tests/e2e/tabs.spec.ts ("#786 — les fleches deplacent le focus") and packages/tests/TU/components/Tabs/tabs-keyboard-focus.spec.ts.

Disabled tabs are skipped by arrow navigation and cannot be focused via Home / End.

Imperative API ​

<OrigamTabs> exposes navigation helpers through defineExpose:

MethodEffect
next()Move selection to the next non-disabled tab.
prev()Move selection to the previous non-disabled tab.
select(id, value)Toggle a specific tab by internal id.
filterProps()Mixin pass-through.
vue
<template>
    <OrigamTabs ref="tabsRef" v-model="active">…</OrigamTabs>
    <OrigamBtn text="Next" @click="tabsRef?.next()" />
</template>