Rolling Base Component

⭐Star

👑Pioneer

TuiRolling is a high-performance, full-featured universal scrolling container. It serves not only as the underlying engine for other TechUI scrolling components but also as a standalone business component. You can use it to easily implement interaction effects such as seamless marquees, automated list scrolling, and custom carousels.

It supports the operation of components including TuiRollingNavIcon, TuiRollingNavTabs, TuiRollingNotification, TuiRollingProgress, and TuiRollingTable.

Core Features

• Omnidirectional Scrolling: Perfect support for scrolling in four directions: up (up), down (down), left (left), and right (right).

• Dual-Mode Engine:

• Item Mode: Scrolls element by element; supports seamless infinite loops (marquees/lists).

• Page Mode: Scrolls by flipping pages based on the visible area (carousels/paginated lists).

• Smart Completion: When data is insufficient to fill the viewport, it supports automatic data cloning (fillData) to maintain a full visual effect, or it can keep the original state.

• Motion Blur: Built-in high-performance motionBlur simulates real visual blur during fast scrolling to improve smoothness.

• Built-in Controls: Provides out-of-the-box control bars (arrows/indicators) with support for flexible layout positioning.

Basic Usage

Automated List Scrolling (Item Mode)

The most common scenario is used to display constantly updating lists (such as winner lists or real-time logs). Set the direction="up" and visibleLength properties.

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

const list = ref(["User A won $100", "User B won $50", "User C won $200", "User D..."]);
</script>

<template>
  <div style="height: 300px; border: 1px solid #eee;">
    <TuiRolling :visibleLength="5" direction="up" autoRolling>
      <TuiRollingItem v-for="(text, index) in list" :key="index">
        <div class="list-item">{{ text }}</div>
      </TuiRollingItem>
    </TuiRolling>
  </div>
</template>

<style scoped>
.list-item { height: 100%; display: flex; align-items: center; padding: 0 15px; }
</style>

Horizontal Marquee (Marquee)

Set the direction to left and enable seamless mode for infinite loops.

<TuiRolling direction="left" :visibleLength="3" seamless :interval="0" :duration="5000">
  <TuiRollingItem v-for="img in images" :key="img.id">
    <img :src="img.src" class="carousel-img" />
  </TuiRollingItem>
</TuiRolling>

Scrolling Modes

Item Mode (Default)

Steps through elements one by one. Suitable for continuous data streams.

Page Mode

Scrolls by "page," where the distance of each scroll equals the size of the visible area. Suitable for traditional carousels or split-screen displays.

<TuiRolling mode="page" direction="right" controlType="indicator" ... />

Control Bars and Interaction

TuiRolling features a powerful built-in control bar system, allowing you to control scrolling without manually writing buttons.

• controlType: Type of controller: arrow (arrows) or indicator (dots/indicators).
• controlAlign: Alignment (start, center, end).
• controlDirection: The layout direction of the control bar (h, v) and its position.

<template>
  <TuiRolling 
    direction="up" 
    controlType="indicator" 
    controlDirection="vr" 
    trigger="hover"
  >
    ...
  </TuiRolling>
</template>

Data Filling Strategy

When the number of incoming data items is less than the visibleLength:

• fillData = true (Default): The component automatically clones data to fill the visible area, ensuring the scrolling effect looks visually full.
• fillData = false: Keeps the original state; if data is insufficient, it leaves blank space and typically disables scrolling automatically.

API Reference

Props

Property	Type	Default	Description
direction	String	'up'	Scrolling direction. Options: up, down, left, right.
mode	String	'item'	Scrolling mode. Options: item (by item), page (by page).
visibleLength	Number	4	Core Property. Number of elements displayed in the visible area.
autoRolling	Boolean	true	Whether to start scrolling automatically.
interval	Number	-	Time interval for auto-scrolling (ms).
duration	Number	-	Duration of a single scroll animation (ms).
seamless	Boolean	true	Whether to enable seamless loop scrolling.
fillData	Boolean	true	Whether to auto-fill data to fill the container when data is less than one page.
initIndex	Number	-	Initial display index position.
hoverPause	Boolean	true	Whether to pause auto-scrolling on mouse hover.
motionBlur	Boolean	true	Whether to enable the motion blur effect during scrolling.
showControl	Boolean	true	Whether to display the control bar.
controlType	String	-	Control bar type. Options: arrow, indicator.
controlAlign	String	'center'	Control bar alignment. Options: start, center, end.
controlDirection	String	'v'	Control bar layout direction: v (vertical), h (horizontal), vr (vertical reverse), hr (horizontal reverse).
trigger	String	'click'	Indicator trigger method. Options: click, hover.
delay	Number	1000	Initialization delay time (ms).
resizeObserver	String	'global'	Size monitoring strategy: self, global, none.

Emits

Event Name	Description	Callback Parameters
start	Triggered when scrolling starts.	-
rolling	Triggered continuously during the scrolling process.	(offset)
update	Triggered when the index is updated.	(currentIndex)

Exposed Methods

Internal methods can be called via ref for fine-grained control:

Method Name	Description	Parameters
play	Starts auto-scrolling.	-
stop	Stops auto-scrolling.	-
toggle	Toggles between play/pause states.	-
prev	Scrolls to the previous item/page.	-
next	Scrolls to the next item/page.	-
goTo	Jumps to a specified index.	(index: Number)
getInfo	Gets current scroll status info (index, position, etc.).	-
forceUpdate	Forces a layout update trigger.	-

Slots

Slot Name	Description
default	Place the list of TuiRollingItem components.