Tabs

TuiTabs is an extremely flexible tab switching component. It breaks the limitations of traditional Tabs that can only be displayed horizontally, supporting layouts in all four directions (up, down, left, right), and providing a variety of appearance styles. It can be used both as a content switcher and as an in-page navigation bar.

Core Features

• Omnidirectional Layout: Supports the faceTo attribute to control tab orientation (up/down/left/right), easily implementing side navigation or bottom menus.
• Three Appearances: Provides three styles: simple, card, and button (button/segmented controller).
• Dual-Mode Rendering: Supports pure data-driven rendering via the options array, as well as slot-based development using the <TuiTab> component.
• Smart Scrolling: Supports enabling scrollable mode for scrolling when the number of tabs exceeds the container size.
• Badge Integration: Built-in Badge support to easily display unread counts or status markers.

Basic Usage

Component Slot Mode

Build tabs using the <TuiTab> sub-component. This is the most intuitive usage, suitable for scenarios requiring high customization of each tab's content.

<script setup>
import { ref } from 'vue';
const activeName = ref(0);
</script>

<template>
  <TuiTabs v-model="activeName">
    <TuiTab :value="0" label="User Management" icon="tui-icon ti-user" />
    <TuiTab :value="1" label="System Settings" icon="tui-icon ti-settings" />
    <TuiTab :value="2" label="Permission Config" disabled />
  </TuiTabs>
</template>

Data Driven Mode

Pass a configuration array through the options attribute. The code is more concise and suitable for dynamically generated tab lists.

<script setup>
import { ref } from 'vue';
const activeId = ref('a');

const tabOptions = [
  { label: 'Home', value: 'a', icon: 'ti-home' },
  { label: 'Messages', value: 'b', count: 12, tagType: 'danger' }, // With Badge
  { label: 'Settings', value: 'c' }
];
</script>

<template>
  <TuiTabs v-model="activeId" :options="tabOptions" />
</template>

Appearance Styles

Switch visual styles through the appearance attribute.

• simple (Default): A minimalist style that indicates the selected state with an underline (or side line).
• card: A card style that simulates folder tabs with a border wrap.
• button: A button style (segmented controller), often used for mode switching within forms.

<template>
  <TuiTabs appearance="card" v-model="val1" :options="opts" />
  
  <TuiTabs 
    appearance="button" 
    :tagConfig="{ tone: 'strong', round: true }" 
    v-model="val2" 
    :options="opts" 
  />
</template>

Orientation and Text Layout

The power of TuiTabs lies in its ability to adapt to various layout requirements.

• faceTo: Controls the position of the Tab bar relative to the content.
  • up (Default): Standard top navigation.
  • down: Bottom navigation.
  • left: Left vertical navigation.
  • right: Right vertical navigation.
• textDirection: Controls the text arrangement direction.
  • h (Default): Horizontal arrangement.
  • v: Vertical arrangement (often used with faceTo="left/right" to achieve a vintage or special sidebar effect).

<template>
  <TuiTabs 
    faceTo="left" 
    textDirection="v" 
    style="height: 400px"
    v-model="active" 
    :options="sideOptions" 
  />
</template>

Scroll Mode

When the number of tabs exceeds the container width (or height), set scrollable to true to enable scroll mode. The component will automatically display left/right (or up/down) switching arrows.

<template>
  <div style="width: 400px">
    <TuiTabs 
      scrollable 
      :scrollOffset="50"
      v-model="active" 
      :options="longOptions" 
    />
  </div>
</template>

Badges and Status

Each Tab item supports displaying a Badge.

• count: The numerical value or text to display.
• tagType: The semantic color of the badge (primary, danger, warning, etc.).
• tagConfig: Configuring tagConfig on TuiTabs allows unified control of all badge styles (such as round, tone).

<template>
  <TuiTabs 
    :tagConfig="{ tone: 'strong', round: true }" 
    :options="[
       { label: 'Todo', count: 5, tagType: 'danger' },
       { label: 'In Progress', count: 12, tagType: 'primary' }
    ]" 
  />
</template>

API Reference

TuiTabs Props

Property	Type	Default	Description
modelValue	String/Number	-	Two-way binding. Currently selected Tab value.
options	Array	[]	Data source configuration. See TuiTab Props below for item object structure.
appearance	String	'simple'	Appearance style. Options: simple, card, button.
faceTo	String	'up'	Orientation. Options: up, down, left, right.
textDirection	String	null	Text direction. Options: h (horizontal), v (vertical). Auto-adapts if empty.
size	String	'default'	Size. Options: default, large, small.
align	String	null	Alignment. Options: start, center, end.
hideBaseLine	Boolean	false	Whether to hide the bottom decorative line (only valid in simple/card modes).
itemMaxWidth	Number/String	-	Maximum width of a single Tab item.
scrollable	Boolean	false	Whether to enable scroll mode.
scrollOffset	Number	0	Extra offset when scrolling.
tagConfig	Object	-	Props passed transparently to the internal TuiTag components (e.g., tone, round).
tipConfig	Object	-	Unified configuration passed to Tooltip.

TuiTab Props (or Options Object Fields)

Property	Type	Default	Description
value	String/Number	Required	Unique identification value.
label	String	-	Tab text (default slot content in Slot mode).
icon	String	null	Icon class name.
count	Number	0	Badge value. Displays when greater than 0.
tagType	String	'default'	Badge color type (danger, primary, etc.).
disabled	Boolean	false	Whether the option is disabled.

Events

Event Name	Description	Callback Parameters
change	Triggered when switching options.	`(value: String
update:modelValue	Two-way binding update.	(value)