Rolling Tab Navigation

⭐Star

👑Pioneer

RollingNavTabs is a rolling navigation component designed to handle variable-length tab lists. It is also built upon the TuiRolling engine, inheriting smooth inertial scrolling and dynamic blur characteristics.

Unlike icon navigation, RollingNavTabs is specifically designed for Tabs scenarios. It supports inserting fixed operation areas (such as "Add Button" or "Menu Button") at the head and tail of the scrolling area. This makes it highly suitable for multi-document editors, tab navigation in administrative back-end systems, and similar use cases.

Core Features

• Powered by TuiRolling: Offers extreme scrolling performance and supports seamless scrolling for a massive number of tabs.
• Head and Tail Slot System: Provides prefix and suffix slots, allowing fixed elements (such as settings icons or collapse menus) to reside at the "front" and "rear" of the scrolling area.
• Flexible Control Bar: The pagination controller can be configured in the head (prefix) or tail (suffix), and supports reversing the sequence with slot content.
• Dual-Layout: Supports Horizontal and Vertical modes.
• Rich Interaction: Supports tab closing, locking, and disabled states, as well as drag-scrolling.

Basic Usage

Horizontal Mode

The most common form of tab navigation. Use TuiRollingNavTabs to wrap TuiRollingNavTab child components.

<script setup>
import { ref } from 'vue';

const activeTab = ref('tab1');
const tabs = [
  { label: 'Dashboard', value: 'tab1', icon: 'ti-home', locked: true }, // Locked and cannot be closed
  { label: 'Settings', value: 'tab2', icon: 'ti-settings' },
  { label: 'Profile', value: 'tab3' },
];

const handleRemove = (index) => {
  tabs.splice(index, 1);
};
</script>

<template>
  <TuiRollingNavTabs 
    v-model="activeTab" 
    direction="h"
    closeable
  >
    <TuiRollingNavTab 
      v-for="(item, index) in tabs" 
      :key="item.value"
      :index="index"
      :value="item.value" 
      :label="item.label" 
      :icon="item.icon"
      :locked="item.locked"
      @remove="handleRemove(index)"
    />
  </TuiRollingNavTabs>
</template>

Vertical Mode

Set direction="v" to switch to a sidebar tab mode. Often used for side toolbars or vertical menus.

<template>
  <div style="height: 400px; width: 160px">
    <TuiRollingNavTabs 
      v-model="activeTab" 
      direction="v"
      :itemApproxHeight="40"
    >
      <TuiRollingNavTab 
        v-for="(item, index) in tabs" 
        :key="item.value"
        v-bind="item" 
        :index="index"
      />
    </TuiRollingNavTabs>
  </div>
</template>

Layout and Slots

The power of RollingNavTabs lies in its flexible area division:

• Prefix Slot
• Controller
• Scrolling Viewport
• Controller
• Suffix Slot

Injecting Fixed Content

Fixed operation buttons can be added to both ends of the scrolling area through the #prefix and #suffix slots.

<TuiRollingNavTabs>
  <TuiRollingNavTab ... />

  <template #prefix>
    <i class="tui-icon ti-settings"></i>
  </template>

  <template #suffix>
    <i class="tui-icon ti-plus"></i>
  </template>
</TuiRollingNavTabs>

Control Bar Position and Reversal

• controlPosition: Determines whether the pagination controller (< > arrows) is displayed at the head (prefix) or tail (suffix).
• prefixReverse / suffixReverse: Determines the arrangement order of the controller and slot content.
• Default: [Slot Content] [Controller] ...
• Reversed: [Controller] [Slot Content] ...

<template>
  <TuiRollingNavTabs 
    controlPosition="prefix" 
    prefixReverse
  >
    <template #prefix><span>Logo</span></template>
    </TuiRollingNavTabs>
</template>

API Reference

TuiRollingNavTabs Props

Property	Type	Default	Description
modelValue	String/Number	-	The currently active Tab value.
direction	String	'h'	Rolling direction. Options: 'h', 'v'.
itemApproxWidth	Number	140	(Horizontal mode) Approximate width of an Item, used for virtual scrolling calculations.
itemApproxHeight	Number	40	(Vertical mode) Approximate height of an Item.
controlPosition	String	-	Control bar position. Options: 'prefix' (Head), 'suffix' (Tail).
prefixReverse	Boolean	false	Whether to reverse the order of the prefix area (slot and controller).
suffixReverse	Boolean	false	Whether to reverse the order of the suffix area (slot and controller).
closeable	Boolean	false	Whether to display a close button.
motionBlur	Boolean	true	Whether to enable rolling dynamic blur.
resizeObserver	String	'global'	Size monitoring strategy: self, global, none.
duration	Number	-	Duration of the rolling animation.

TuiRollingNavTab Props

Property	Type	Default	Description
value	String/Number	-	Unique identifier value of the Tab.
label	String	-	Display text.
icon	String	-	Icon class name.
index	Number	-	Required. Index value used to calculate scrolling position.
disabled	Boolean	false	Whether it is disabled.
locked	Boolean	false	Whether it is locked (cannot be closed even if closeable is enabled).

Emits

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the selected value changes.	(value)
change	Triggered when the selected item changes.	(value, index)
start	Triggered when scrolling starts.	-
rolling	Triggered continuously during the scrolling process.	(offset)

Slots

Slot Name	Description
default	Place the TuiRollingNavTab list here.
prefix	Slot for fixed content at the head.
suffix	Slot for fixed content at the tail.