Van Rolling Text

Vant RollingText Component

Rolling text animation component that can roll numbers and other types of text with smooth animation effects.

When to Invoke

Invoke this skill when:

• User needs to create animated number counters
• User wants to implement slot machine-style rolling effects
• User needs to display rolling text animations
• User wants to create countdown or count-up animations
• User asks about number animation effects

Features

• Number Rolling: Roll from start number to target number
• Direction Control: Support up and down rolling directions
• Stop Order: Control the order of stopping animation for each digit
• Non-numeric Text: Support rolling non-numeric text arrays
• Custom Style: Customizable height, color, and font size
• Manual Control: Start and reset methods for programmatic control
• Auto Start: Option to automatically start animation on mount

API Reference

Props

Methods

Use ref to get RollingText instance and call instance methods.

Types

import type {
  RollingTextProps,
  RollingTextInstance,
  RollingTextDirection,
  RollingTextStopOrder,
} from 'vant';

CSS Variables

Usage Examples

Basic Usage

<template>
  <van-rolling-text :start-num="0" :target-num="123" />
</template>

Set Rolling Direction

<template>
  <van-rolling-text :start-num="0" :target-num="432" direction="up" />
</template>

Set Stop Order

<template>
  <van-rolling-text :start-num="0" :target-num="54321" stop-order="rtl" />
</template>

Roll Non-numeric Text

<template>
  <van-rolling-text :text-list="textList" :duration="1" />
</template>

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

const textList = ref([
  'aaaaa',
  'bbbbb',
  'ccccc',
  'ddddd',
  'eeeee',
  'fffff',
  'ggggg',
]);
</script>

Custom Style

<template>
  <van-rolling-text
    class="my-rolling-text"
    :height="54"
    :start-num="12345"
    :target-num="54321"
  />
</template>

<style>
.my-rolling-text {
  --van-rolling-text-background: #1989fa;
  --van-rolling-text-color: white;
  --van-rolling-text-font-size: 24px;
  --van-rolling-text-gap: 6px;
  --van-rolling-text-item-border-radius: 5px;
  --van-rolling-text-item-width: 40px;
}
</style>

Manual Control

<template>
  <van-rolling-text
    ref="rollingTextRef"
    :start-num="0"
    :target-num="54321"
    :auto-start="false"
  />
  <van-grid clickable :column-num="3">
    <van-grid-item icon="play-circle-o" text="Start" @click="start" />
    <van-grid-item icon="replay" text="Reset" @click="reset" />
  </van-grid>
</template>

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

const rollingTextRef = ref(null);

const start = () => {
  rollingTextRef.value?.start();
};

const reset = () => {
  rollingTextRef.value?.reset();
};
</script>

Counter Animation

<template>
  <div class="counter-demo">
    <van-rolling-text
      ref="counterRef"
      :start-num="startValue"
      :target-num="targetValue"
      :duration="2"
    />
    <van-button type="primary" @click="animate">
      Animate
    </van-button>
  </div>
</template>

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

const counterRef = ref(null);
const startValue = ref(0);
const targetValue = ref(9999);

const animate = () => {
  counterRef.value?.reset();
  setTimeout(() => {
    counterRef.value?.start();
  }, 100);
};
</script>

Best Practices

1. Use appropriate duration: Set duration based on the number of digits for smooth animation
2. Manual control for complex scenarios: Use auto-start="false" when you need precise control
3. Custom styling: Use CSS variables for consistent styling across the app
4. Text array consistency: Ensure all items in text-list have the same length
5. Reset before restart: Call reset() before start() when re-animating