Rolling Icon Navigation

⭐Star

👑Pioneer

RollingNavIcon is a rolling navigation component used to display a large number of icon entries. It is built upon TechUI's powerful core rolling engine, TuiRolling. It inherits the high-performance features of TuiRolling, supporting scrolling by item or page, seamless infinite scrolling, adaptive layout, and smooth motion blur effects.

It is ideal for toolbars, shortcut entry lists, or navigation menus on mobile terminals.

Core Features

• Powered by TuiRolling: Developed based on the core rolling component, it possesses powerful rolling calculation capabilities, supporting seamless loops and adaptive padding.
• Dual-Layout: Perfectly supports both Horizontal and Vertical flow directions.
• Visual:
  • Frame Shape: Supports rounded corners (round), circles (circle), or no border (none).
  • Motion Blur: Built-in motionBlur provides high-quality visual dynamic blur during fast scrolling.
  • Size Control: Precisely control icon size, frame width/height, and adaptive approximate width/height.
• Interaction Control:
  • Supports Click or Hover to trigger selection.
  • Supports Closeable mode, allowing users to dynamically remove navigation items.
  • Flexible Control Bar position configuration (top, bottom, left, right).

Basic Usage

Horizontal Rolling

The default mode. Suitable for top toolbars or full-width menus. The component automatically calculates the number of items displayed per page based on frameWidth and container width.

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

const activeVal = ref('home');
const navItems = [
  { label: 'Dashboard', value: 'home', icon: 'ti-home' },
  { label: 'Components', value: 'comp', icon: 'ti-package' },
  // ... more data
];
</script>

<template>
  <TuiRollingNavIcon 
    v-model="activeVal" 
    direction="h"
    :frameWidth="100" 
    :iconSize="28"
  >
    <TuiRollingNavIconItem 
      v-for="item in navItems" 
      :key="item.value"
      :value="item.value" 
      :label="item.label" 
      :icon="item.icon" 
    />
  </TuiRollingNavIcon>
</template>

Vertical Rolling

Set direction="v" to switch to sidebar mode. In this mode, the control bar (pagination buttons) will automatically adapt to the layout. It is usually recommended to adjust the position using controlPosition.

<template>
  <div style="height: 400px; width: 120px">
    <TuiRollingNavIcon 
      v-model="activeVal" 
      direction="v"
      frameShap="circle"
      controlPosition="bottom"
    >
      <TuiRollingNavIconItem 
        v-for="item in navItems" 
        :key="item.value"
        v-bind="item" 
      />
    </TuiRollingNavIcon>
  </div>
</template>

Interaction and Visual

Trigger and Close

• trigger: Set to 'hover' to enable selection upon mouse hover.
• closeable: When enabled, a close button appears when hovering over an Item. Listen to the @remove event to handle deletion logic.

<template>
  <TuiRollingNavIcon 
    trigger="hover" 
    closeable
    frameShap="round"
  >
    <TuiRollingNavIconItem 
      v-for="(item, index) in list" 
      :key="item.id"
      v-bind="item"
      @remove="handleRemove(index)"
    />
  </TuiRollingNavIcon>
</template>

Control Bar Position

The pagination controller can be placed at any position—top, bottom, left, or right—via controlPosition to suit different UI designs.

API Reference

Props

Property	Type	Default	Description
modelValue	String/Number	-	The currently selected value (v-model).
direction	String	'h'	Rolling direction. Options: 'h' (Horizontal), 'v' (Vertical).
controlPosition	String	-	Control bar position. Options: top, right, bottom, left.
frameShap	String	'round'	Shape of the icon frame. Options: none, round, circle.
trigger	String	'click'	Activation method. Options: click, hover.
closeable	Boolean	false	Whether to enable the delete function.
motionBlur	Boolean	true	Whether to enable the motion blur effect during scrolling.
iconSize	Number	24	Icon size (px).
frameWidth	Number	100	Outer frame width of a single Item.
frameHeight	Number	80	Outer frame height of a single Item.
itemApproxWidth	Number	140	Approximate width for adaptive calculation (used for estimating pagination).
itemApproxHeight	Number	80	Approximate height for adaptive calculation.
controlType	String	-	Style type of the control bar. Options: base, enhanced.
duration	Number	-	Duration of the rolling animation.
resizeObserver	String	'global'	Size monitoring strategy: self, global, none.

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 scrolling.	(offset)

Slots

Slot Name	Description
default	The list of <TuiRollingNavIconItem> components should be placed here.