Tabs

Overview

VyTabs renders an animated tab indicator, selectable triggers, and optional content panels on top of the @vyui/core tabs primitives. It supports horizontal and vertical layouts, pill and link treatments, controlled or uncontrolled state, icons, disabled items, static content, and named content slots.

Usage

<script setup lang="ts">
import { ref } from 'vue'
import { VyTabs } from '@vyui/kit'

const active = ref('overview')
const items = [
  {
    label: 'Overview',
    value: 'overview',
    icon: 'i-lucide-layout-dashboard',
    content: 'Your account summary and recent activity.',
  },
  {
    label: 'Security',
    value: 'security',
    icon: 'i-lucide-shield-check',
    content: 'Passkeys, passwords, and signed-in devices.',
  },
  {
    label: 'Billing',
    value: 'billing',
    icon: 'i-lucide-credit-card',
    content: 'Plan, payment method, and invoices.',
  },
]
</script>

<template>
  <VyTabs v-model="active" :items="items" />
</template>

Give items explicit value fields when state is stored or shared. Without one, VyTabs uses the zero-based index converted to a string, such as '0'.

Named content slots

Set an item's slot to render a different named slot for its panel. Every content slot receives item and index.

<script setup lang="ts">
import { VyButton, VyTabs } from '@vyui/kit'

const items = [
  { label: 'Profile', value: 'profile', slot: 'profile' },
  { label: 'Devices', value: 'devices', slot: 'devices' },
]
</script>

<template>
  <VyTabs :items="items" default-value="profile">
    <template #profile>
      <view class="gap-3 rounded-xl bg-neutral-50 p-4">
        <text class="font-semibold text-neutral-900">Public profile</text>
        <text class="text-sm text-neutral-500">
          Choose the details other people can see.
        </text>
        <VyButton size="sm">Edit profile</VyButton>
      </view>
    </template>

    <template #devices>
      <view class="gap-2 rounded-xl bg-neutral-50 p-4">
        <text class="font-semibold text-neutral-900">Signed-in devices</text>
        <text class="text-sm text-neutral-500">iPhone 16 Pro · Stockholm</text>
        <text class="text-sm text-neutral-500">Pixel 9 · Last active yesterday</text>
      </view>
    </template>
  </VyTabs>
</template>

If item.slot is omitted, the panel uses the content slot. If no matching slot is supplied, item.content is rendered as a text node.

Vertical navigation

Vertical tabs place the trigger rail beside the active panel. Give the component or its parent a useful height when the panel should fill a bounded region.

<script setup lang="ts">
import { VyTabs } from '@vyui/kit'

const sections = [
  { label: 'General', value: 'general', icon: 'i-lucide-settings', content: 'General preferences' },
  { label: 'Privacy', value: 'privacy', icon: 'i-lucide-lock', content: 'Privacy controls' },
  { label: 'About', value: 'about', icon: 'i-lucide-info', content: 'App and legal information' },
]
</script>

<template>
  <VyTabs
    class="h-64"
    :items="sections"
    default-value="general"
    orientation="vertical"
    variant="link"
  />
</template>

Crowded mobile tabs

Use direction="stacked" to place an icon above its label when several horizontal triggers share a narrow phone width.

<VyTabs
  v-model="active"
  :items="destinations"
  direction="stacked"
  size="sm"
  :content="false"
/>

Set content="false" when the tabs only control content rendered elsewhere.

Custom triggers

The trigger slots receive the item and index. The leading slot additionally receives the resolved icon color required for Lynx SVG rendering.

<VyTabs :items="items">
  <template #leading="{ item, iconColor }">
    <VyIcon :name="item.icon" :color="iconColor" />
  </template>

  <template #default="{ item }">
    {{ item.shortLabel ?? item.label }}
  </template>

  <template #trailing="{ item }">
    <VyBadge v-if="item.count" :label="String(item.count)" size="sm" />
  </template>
</VyTabs>

Features and behavior

• Bind v-model to control the active item, or use defaultValue for uncontrolled state.
• defaultValue defaults to '0', matching the first item only when that item uses its fallback value.
• Each item uses value as its identity; otherwise it uses String(index).
• Disabled items are dimmed and ignore taps.
• content="false" omits every content panel while keeping the tab triggers interactive.
• Inactive panels are currently removed from the tree. Although unmountOnHide is forwarded to the core root, the current content primitive does not preserve hidden panels when it is false.
• The indicator measures the active native Lynx trigger and updates after layout changes.
• Item data is forwarded unchanged to trigger and content slot props.

Tab item

Props

Color defaults to primary, secondary, success, info, warning, error, or neutral, and supports consumer registry extensions.

Emits

Slots

Styling and theming

Override globally through appConfig.ui.tabs or locally with ui.

Theme variants

The theme also reacts to the core trigger's active, inactive, and disabled state. Pill triggers divide the horizontal rail evenly; link triggers size to their content.

Accessibility

Each core trigger is exposed as an accessibility element with tab semantics. The active trigger announces a selected state, and a disabled item announces disabled state and cannot be activated.

Use concise, unique labels and keep visible text in custom trigger slots. Icon-only tabs need an accessible naming strategy, but the current kit wrapper does not expose a per-item accessibility-label field, so prefer visible labels for production navigation. Do not rely only on the indicator color to communicate selection.

Platform notes

• The indicator uses native Lynx element measurement rather than DOM offsets. It remains hidden until the first non-zero layout measurement to avoid flashing at the wrong position.
• Lynx SVG does not inherit currentColor; built-in icons receive a resolved fill, and the leading slot receives the same iconColor.
• Inactive content is currently conditionally rendered regardless of unmountOnHide; do not rely on hidden panels retaining local component state.
• The theme uses vyui's semantic tokens, so it adapts automatically under dark mode (see Theming → Dark Mode), and intentionally omits DOM focus-ring and hover behavior.
• Long built-in labels truncate. Use direction="stacked", fewer tabs, or a vertical layout when a narrow horizontal rail becomes crowded.

Related components

• Accordion for independently collapsible sections.
• BottomNavigation for primary app-level destinations.
• SegmentedControl for choosing one value without associated content panels.