Digital Flip

v0.0.5+

TuiDigitalFlip is a numerical display component featuring a mechanical flip effect. By simulating the dynamic movement of physical flip cards, it makes numerical changes more visually engaging. It is commonly used for data dashboards, statistical boards, or countdown scenarios.

Usage Scenario

The flip effect is more prominent on larger cards. Although size: small is supported, it is recommended to use sizes of size: default or larger.

Basic Usage

Basic Display

The simplest usage is to bind the value. The component automatically handles numerical changes and triggers the flip animation. It supports integers, floating-point numbers, and time strings (e.g., "12:30:59").

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

const num = ref(12345);
</script>

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

Formatting

Thousands and Decimals

• useGrouping: Enables the thousands separator (e.g., 1,234,567).
• Decimal Support: The component automatically recognizes and retains decimal points without extra configuration.

<template>
  <TuiDigitalFlip :value="123456" useGrouping />
  
  <TuiDigitalFlip :value="123.45" />
</template>

Prefix & Suffix

Use the prefix and suffix attributes to add units or symbols to the value, such as currency symbols or percentages.

<template>
  <TuiDigitalFlip :value="1234" prefix="$ " />
  
  <TuiDigitalFlip :value="85" suffix=" %" />
  
  <TuiDigitalFlip :value="122" prefix="Output " suffix=" tons" />
</template>

Animation Control

Flip Speed and Delay

• duration: Duration of the flip animation in milliseconds (ms), default is 600.
• delay: Delay time before the first load or numerical change animation triggers (ms).

<template>
  <TuiDigitalFlip :value="88888" :duration="300" />
  
  <TuiDigitalFlip :value="12345" :delay="3000" />
</template>

Flip Mode

The flipMode attribute controls the logic of numerical scrolling:

• shortest (Default): Selects the shortest path for scrolling (e.g., flipping 9 -> 0 directly downwards).
• downOnly: Always scrolls downwards (simulating a traditional mechanical watch).
• smart: Intelligent mode that selects the direction automatically based on the numerical change.

<TuiDigitalFlip :value="count" flipMode="downOnly" />

Appearance

Sizes and Styles

• size: Built-in sizes include huge, large, default, small, and custom.

• appearance:

• default: Standard style (typically dark background with light text).

• reverse: Inverted style (light background with dark text).

• bordered: Whether to display borders for individual digits.

• dropShadow: Whether to display drop shadows.

<template>
  <TuiDigitalFlip :value="12345" size="large" appearance="reverse" bordered />
</template>

Custom Styles

Set size="custom" and pass a customClass to deeply customize the width, height, font size, and color scheme of the flip component via CSS variables.

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

<style lang="less">
.my-flip-style {
  /* Define Dimensions */
  --tui-dflip-fz: 20px;   /* Font size */
  --tui-dflip-lh: 24px;   /* Line height */
  --tui-dflip-w: 24px;    /* Single card width */
  --tui-dflip-h: 30px;    /* Single card height */
  
  /* Define Colors */
  --tui-dflip-fc: #e6a23c;       /* Font color */
  --tui-dflip-bg: #409eff;       /* Card background */
  --tui-dflip-bg_alt: #66b1ff;   /* Flip side background */
}
</style>

API Reference

Props

Property	Type	Default	Description
value	String/Number	0	Required. Numerical value or time string to display.
duration	Number	600	Flip animation duration (ms).
delay	Number	1000	Animation delay start time (ms).
flipMode	String	'shortest'	Flip mode. Options: smart, downOnly, shortest.
useGrouping	Boolean	false	Whether to enable the thousands separator.
prefix	String	-	Prefix text.
suffix	String	-	Suffix text.
gap	Number	-	Spacing between digits (px).
size	String	'default'	Size. Options: huge, large, default, small, custom.
appearance	String	'default'	Appearance style. Options: default, reverse, custom.
bordered	Boolean	false	Whether to display borders.
dropShadow	Boolean	false	Whether to display shadows.
customClass	String	-	Custom class name used with size="custom".