Digital Rolling

🧬Ported from [VueDigitalTransform]

TuiDigitalRolling is a numerical display component that simulates a rolling effect similar to an "odometer" or "slot machine." Unlike the mechanical folding feel of a Flip counter, it provides smooth vertical scrolling animations. The component supports "Dislocation" scrolling to simulate physical inertia, making it ideal for displaying real-time growing sales figures, statistical data, or clocks.

Basic Usage

Basic Display

The simplest usage only requires binding the value. The component automatically handles numerical changes and triggers the scrolling animation. It supports integers, decimals, and time format strings (e.g., "12:30:59").

<script setup>
import { ref } from 'vue';
const num = ref(12345);
</script>

<template>
  <TuiDigitalRolling :value="num" />
</template>

Scrolling Mechanism

Control the rhythm of the numerical scroll via the dislocation property to adapt to different business scenarios.

• false (Default): Uniform Rhythm. All numerical digits start scrolling simultaneously. Suitable for counters, countdowns, or clocks where synchronicity is emphasized.
• true: Dislocated Scrolling. Simulates a real physical roller where higher and lower digits have different scrolling distances and durations, creating an odometer-like physical inertia. Suitable for displaying large statistical data.

<template>
  <TuiDigitalRolling value="12:00:00" :dislocation="false" />
  
  <TuiDigitalRolling :value="987654" :dislocation="true" :interval="1000" />
</template>

Formatting and Symbols

Thousands Separator and Punctuation Handling

• useGrouping: Enables the thousands separator.
• includeSymbols: Controls the scrolling behavior of punctuation marks (decimal points, commas).
• false (Default): Punctuation remains fixed; only digits scroll.
• true: Punctuation marks participate in the scrolling animation.

<template>
  <TuiDigitalRolling :value="1234.56" useGrouping />

  <TuiDigitalRolling :value="1234.56" useGrouping includeSymbols />
</template>

Prefix and Suffix

Add units via the prefix and suffix props.

<TuiDigitalRolling :value="88" prefix="$ " suffix=" %" />

Appearance and Layers

Appearance Layer

TuiDigitalRolling provides a unique appearanceLayer control, which determines the application scope of backgrounds, borders, and shadows:

• group (Default): Treats the entire numerical string as a whole, wrapping the background and border around the outermost layer.
• item: Each individual digit (Digit) has its own independent background and border.
• none: No background style.

<template>
  <TuiDigitalRolling :value="12345" appearanceLayer="group" bordered />
  
  <TuiDigitalRolling :value="12345" appearanceLayer="item" bordered :gap="4" />
</template>

Style Customization

• bordered: Displays a border.
• dropShadow: Displays a drop shadow.
• appearance: default (Dark background, light text) / reverse (Light background, dark text).
• gap: The spacing between digits (px).

Custom Styles

Set size="custom" and pass a customClass. You can then use CSS variables to precisely control every detail of the roller, including font size, the dimensions of individual digit blocks, and colors.

<template>
  <TuiDigitalRolling 
    :value="12345" 
    size="custom" 
    appearance="custom"
    customClass="my-rolling-style" 
  />
</template>

<style lang="less">
.my-rolling-style {
  /* Define Dimensions */
  --tui-droll-fz: 20px;   /* Font size */
  --tui-droll-lh: 24px;   /* Line height */
  --tui-droll-w: 24px;    /* Single digit width */
  --tui-droll-h: 30px;    /* Single digit height */
  
  /* Define Colors */
  --tui-droll-fc: #e6a23c;       /* Font color */
  --tui-droll-bg: #409eff;       /* Background color */
  --tui-droll-bd: #66b1ff;       /* Border color */
  --tui-droll-shadow: 0 2px 4px rgba(0,0,0,0.2); /* Shadow */
}
</style>

API Reference

Props

Property	Type	Default	Description
value	String/Number	0	Required. The numerical value to display.
dislocation	Boolean	false	Whether to enable dislocated scrolling (simulating physical inertia).
interval	Number	500	Duration of the scrolling animation (ms).
appearanceLayer	String	'group'	The layer where the appearance style is applied. Options: group (entirety), item (individual digit), none.
useGrouping	Boolean	false	Whether to enable thousands separators.
includeSymbols	Boolean	false	Whether punctuation marks (commas, decimal points) participate in the scrolling animation.
prefix	String	-	Prefix text.
suffix	String	-	Suffix text.
delay	Number	-	Delay before the animation triggers (ms).
gap	Number	-	Spacing between digits (px).
size	String	'default'	Size. Options: huge, large, default, small, custom.
appearance	String	'default'	Color scheme style. Options: default, reverse, custom.
bordered	Boolean	false	Whether to display a border.
dropShadow	Boolean	false	Whether to display a shadow.
customClass	String	-	Custom class name, used in conjunction with size="custom".

Credits

DakerHub

Github

This component is ported from the open-source component vue-digital-transform. Based on the TechUI global theme, it has undergone deep customization and the addition of numerous APIs, greatly enhancing its capabilities.

We would like to express our sincere gratitude and respect to the original author, DakerHub!!