Navigation Menu

TuiNav is a highly integrated, data-driven navigation component.

Unlike traditional menus built through DOM nesting (such as <ul><li>), TuiNav is rendered entirely based on JSON data. This means you only need to maintain a single routing table or menu configuration array to automatically generate a complete navigation system with multi-level nesting, responsive shrinkage, and fold animations.

Core Features

• Data-Driven: Automatically renders multi-level menus by passing a JSON tree structure through the data attribute.
• Dual-Layout: Supports Horizontal top bar mode and Vertical sidebar mode.
• Intelligent Response:
  • Horizontal Mode: When space is insufficient, it automatically calculates and collapses redundant menu items into a "..." dropdown menu.
  • Vertical Mode: Supports one-click collapse into an icon-only navigation (Mini Sidebar).
• Rich Interaction: Built-in accordion mode, customizable trigger methods (Click/Hover), and router integration.

Basic Usage

Data Structure

The core of the component relies on the data attribute. The default data field structure is as follows (custom mapping is available via the props attribute):

const menuData = [
  { 
    id: "1", 
    label: 'Dashboard', 
    icon: 'tui-icon ti-home', // Icon class name
    children: [               // Sub-menus
      { id: "1-1", label: 'Console' },
      { id: "1-2", label: 'Monitoring' }
    ]
  },
  { 
    id: "2", 
    label: 'Settings', 
    disabled: true // Disabled state
  }
];

Vertical Navigation

Default mode (direction="v"). Suitable for sidebars.

<template>
  <div style="width: 250px;">
    <TuiNav 
      :data="menuData" 
      :defaultOpened="['1']"
      @change="handleChange"
    />
  </div>
</template>

Horizontal Navigation

Set direction="h" to enable horizontal mode. When ellipsis is enabled, the component will automatically calculate based on the container width and collect menu items that cannot fit into an ellipsis menu at the end.

<template>
  <TuiNav 
    direction="h"
    :data="menuData" 
    :ellipsis="true"
  />
</template>

Advanced Features

Collapse Mode

Only effective in vertical mode. Set collapse to true, and the menu will shrink to a strip showing only icons. Sub-menus will be displayed in a Popover format.

<template>
  <div style="width: auto;">
    <TuiNav 
      direction="v"
      :collapse="isCollapse" 
      :data="menuData"
    />
    <button @click="isCollapse = !isCollapse">Toggle Collapse</button>
  </div>
</template>

Accordion Mode

Set accordion to true to enable the accordion effect. In this mode, only one menu item at the same level can be expanded at a time; opening a new menu will automatically collapse others.

<TuiNav direction="v" accordion :data="menuData" />

Router Integration

After setting router to true, the component will automatically enable route listening mode.

• Status Synchronization: The component automatically monitors the current route path and sets the corresponding menu item to the Active state.
• Manual Navigation: Clicking a menu item will not automatically trigger route navigation. You need to manually call router.push or custom jump logic within the @change event. This design facilitates the integration of page transition animations (such as TechUI's routerTransition).

<script setup>
import { useRouter } from "vue-router";
const router = useRouter();

// Menu data
const menuData = [
  { id: "/home", label: 'Home', icon: 'ti-home' },
  { id: "/settings", label: 'Settings', icon: 'ti-settings' }
];

// Handle jump logic
const handleChange = (obj) => {
  // obj.item contains the data of the currently clicked menu item
  console.log("Navigating to:", obj.item.id);
  
  // Manually execute route navigation
  router.push(obj.item.id);
  
  // Or use custom transition navigation
  // routerTransition({ path: obj.item.id });
}
</script>

<template>
  <TuiNav 
    router 
    :data="menuData" 
    @change="handleChange"
  />
</template>

API Reference

Props

Core Data and Layout

Property	Type	Default	Description
data	Array	[]	Core data source. Tree structure array.
direction	String	'v'	Navigation direction. Options: 'v' (Vertical), 'h' (Horizontal).
props	Object	{ id:'id', ... }	Data field mapping configuration. Default: { id:'id', children: 'children', label: 'label', disabled: 'disabled' }.
defaultActive	Array	[]	Array of IDs for default selected menu items.
defaultOpened	Array	[]	Array of IDs for default expanded sub-menus.

Interaction Behavior

Property	Type	Default	Description
menuTrigger	String	'global'	Sub-menu trigger method. Options: 'click', 'hover', 'global' (follows global settings).
accordion	Boolean	false	Whether to enable accordion mode (Vertical mode only).
router	Boolean	false	Whether to enable router mode.
collapse	Boolean	false	Whether to collapse the menu (Vertical mode only).

Responsive and Appearance

Property	Type	Default	Description
ellipsis	Boolean	true	Whether to enable automatic ellipsis for horizontal navigation (Horizontal mode only).
ellipsisIcon	String	'tui-icon ti-more-h'	Icon class name for the ellipsis menu.
lineHeight	Number	-	Force specify line height (used for special layout fine-tuning).
resizeObserver	String	'global'	Size monitoring strategy: 'self', 'global', 'none'. Used to trigger ellipsis calculation.
popperOffset	Number	4	Offset distance of the popup menu.
popperDelay	Number	1000	Display/Hide delay of the popup menu (ms).

Events

Event Name	Description	Callback Parameters
change	Triggered when the selected menu item changes.	(item: Object) Data object of the currently selected menu item.
open	Triggered when a sub-menu expands.	(index: String, indexPath: Array) The expanded menu ID and its path.
close	Triggered when a sub-menu collapses.	(index: String, indexPath: Array) The collapsed menu ID and its path.