Counter

Pure native requestAnimationFrame-driven number easing animation with no third-party animation library dependency. Works great with Hero sections and Dashboard statistics displays.

Demo

Preview

基础用法

12,800 + 0 +

组件安装次数

99.9 % 0.0 %

可用性

56 0

内置组件数

prefix 前缀（如货币符号）

$ 9,999 $ 0 ¥ 52,800 ¥ 0

separator 千分位分隔符

1,234,567 0 1.234.567 0 1234567 0

from 起始值

500 100 0 1,000

尺寸：SM / MD / LG / XL

42 0 SM

42 0 MD

42 0 LG

42 0 XL

complete 事件

100 0

变体（仅文字颜色）

128 0 default

128 0 primary

128 0

accent

128 0 success

128 0 danger

Installation

pnpm dlx brutx-vue@latest add counter

Usage

<script setup>
import { Counter } from 'brutx-ui-vue'
import { ref } from 'vue'

const counterRef = ref()
</script>

<template>
    <!-- Basic usage -->
    <Counter :to="12800" suffix="+" size="lg" />

    <!-- Decimal point -->
    <Counter :to="99.9" :decimals="1" suffix="%" />

    <!-- Manual control -->
    <Counter ref="counterRef" :to="500" :auto-start="false" />
    <button @click="counterRef.play()">Start</button>
</template>

Custom Component Prefix/Suffix

<script setup>
import { Counter } from 'brutx-ui-vue'
import { DollarSign, Percent } from 'lucide-vue-next'
</script>

<template>
    <!-- Use component as prefix -->
    <Counter :to="12800" :prefix-component="DollarSign" />

    <!-- Use text as suffix -->
    <Counter :to="99.9" :decimals="1" suffix="%" />

    <!-- Mixed: component prefix + text suffix -->
    <Counter :to="500" :prefix-component="DollarSign" suffix="万" :animate-suffix="false" />
</template>

Variants

variant only affects the number text color, making it easy to highlight statistics on different backgrounds. accent is a bright yellow that has low contrast on light backgrounds; use it on dark or colored backgrounds.

Variant	Description
default	Standard foreground text
primary	Primary (coral) text
accent	Accent (yellow) text
success	Success (green) text
danger	Destructive (red) text

<script setup>
import { Counter } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex flex-wrap items-end gap-6">
        <Counter :to="128" variant="default" size="lg" />
        <Counter :to="128" variant="primary" size="lg" />
        <Counter :to="128" variant="accent" size="lg" />
        <Counter :to="128" variant="success" size="lg" />
        <Counter :to="128" variant="danger" size="lg" />
    </div>
</template>

Sizes

Size	Description
sm	Small font size
md	Default font size
lg	Large font size
xl	Extra large font size

Programmatic Control

Counter exposes the following methods via defineExpose, allowing parent components to call them through ref:

<script setup>
import { ref } from 'vue'
import { Counter } from 'brutx-ui-vue'

const counterRef = ref()
</script>

<template>
    <Counter ref="counterRef" :to="500" :auto-start="false" />
    <button @click="counterRef?.play()">Start</button>
    <button @click="counterRef?.stop()">Stop</button>
</template>

API Reference

Counter — Props

Name	Type	Default	Description
to Required	number	—	The required target value for the count-up animation.
Details Declared type number Default value details Not declared — Source Counter.vue:14 packages/ui/src/components/counter/Counter.vue
from	number | undefined	0	The starting value; play() also restarts from this value.
Details Declared type number | undefined Default value details Declaration 0 Source: packages/ui/src/components/counter/Counter.vue Resolved value 0 Source Counter.vue:15 packages/ui/src/components/counter/Counter.vue
duration	number | undefined	2000	Animation duration in milliseconds; non-positive values use the component default duration.
Details Declared type number | undefined Default value details Declaration DEFAULT_COUNTER_DURATION Source: packages/ui/src/components/counter/Counter.vue Resolved value 2000 Source Counter.vue:16 packages/ui/src/components/counter/Counter.vue
decimals	number | undefined	0	The number of displayed decimal places; values are formatted to this precision.
Details Declared type number | undefined Default value details Declaration 0 Source: packages/ui/src/components/counter/Counter.vue Resolved value 0 Source Counter.vue:17 packages/ui/src/components/counter/Counter.vue
decimalSeparator	string | undefined	"."	The separator displayed between the integer and fractional parts.
Details Declared type string | undefined Default value details Declaration '.' Source: packages/ui/src/components/counter/Counter.vue Resolved value "." Source Counter.vue:18 packages/ui/src/components/counter/Counter.vue
prefix	string | undefined	""	Text displayed before the number, such as a currency symbol.
Details Declared type string | undefined Default value details Declaration '' Source: packages/ui/src/components/counter/Counter.vue Resolved value "" Source Counter.vue:19 packages/ui/src/components/counter/Counter.vue
suffix	string | undefined	""	Text displayed after the number, such as a percent sign or plus sign.
Details Declared type string | undefined Default value details Declaration '' Source: packages/ui/src/components/counter/Counter.vue Resolved value "" Source Counter.vue:20 packages/ui/src/components/counter/Counter.vue
prefixComponent	Component | undefined	undefined	A display component used instead of the text prefix. It is mounted again for layout measurement, so avoid internal state and side effects.
Details Declared type Component | undefined Default value details Declaration undefined Source: packages/ui/src/components/counter/Counter.vue Resolved value undefined Source Counter.vue:25 packages/ui/src/components/counter/Counter.vue
suffixComponent	Component | undefined	undefined	A display component used instead of the text suffix. It is mounted again for layout measurement, so avoid internal state and side effects.
Details Declared type Component | undefined Default value details Declaration undefined Source: packages/ui/src/components/counter/Counter.vue Resolved value undefined Source Counter.vue:26 packages/ui/src/components/counter/Counter.vue
animatePrefix	boolean | undefined	true	Whether to render prefixComponent when provided; when false, the prefix text is shown.
Details Declared type boolean | undefined Literal values false true Default value details Declaration true Source: packages/ui/src/components/counter/Counter.vue Resolved value true Source Counter.vue:27 packages/ui/src/components/counter/Counter.vue
animateSuffix	boolean | undefined	true	Whether to render suffixComponent when provided; when false, the suffix text is shown.
Details Declared type boolean | undefined Literal values false true Default value details Declaration true Source: packages/ui/src/components/counter/Counter.vue Resolved value true Source Counter.vue:28 packages/ui/src/components/counter/Counter.vue
separator	string | undefined	","	The thousands separator. An empty string disables digit grouping while retaining decimalSeparator.
Details Declared type string | undefined Default value details Declaration ',' Source: packages/ui/src/components/counter/Counter.vue Resolved value "," Source Counter.vue:29 packages/ui/src/components/counter/Counter.vue
easing	"ease-out" | "linear" | "ease-in-out" | undefined	"ease-out"	The easing function applied to animation progress.
Details Declared type "ease-out" | "linear" | "ease-in-out" | undefined Literal values "ease-in-out" "ease-out" "linear" Default value details Declaration 'ease-out' Source: packages/ui/src/components/counter/Counter.vue Resolved value "ease-out" Source Counter.vue:30 packages/ui/src/components/counter/Counter.vue
autoStart	boolean | undefined	true	Starts the animation on mount. When false, the value stays at from and to/from changes do not auto-play.
Details Declared type boolean | undefined Literal values false true Default value details Declaration true Source: packages/ui/src/components/counter/Counter.vue Resolved value true Source Counter.vue:31 packages/ui/src/components/counter/Counter.vue
variant	"accent" | "danger" | "default" | "primary" | "success" | undefined	"default"	The number text color variant; it does not change the card background.
Details Declared type NonNullable<"default" | "primary" | "success" | "danger" | "accent" | null | undefined> | undefined Literal values "accent" "danger" "default" "primary" "success" Default value details Declaration 'default' Source: packages/ui/src/components/counter/Counter.vue Resolved value "default" Source Counter.vue:32 packages/ui/src/components/counter/Counter.vue
size	"lg" | "md" | "sm" | "xl" | undefined	"md"	The preset font size for the number.
Details Declared type NonNullable<"lg" | "sm" | "md" | "xl" | null | undefined> | undefined Literal values "lg" "md" "sm" "xl" Default value details Declaration 'md' Source: packages/ui/src/components/counter/Counter.vue Resolved value "md" Source Counter.vue:33 packages/ui/src/components/counter/Counter.vue
title	string | undefined	undefined	Optional heading text. Providing it enables container layout; title-slot content takes precedence.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/counter/Counter.vue Resolved value undefined Source Counter.vue:34 packages/ui/src/components/counter/Counter.vue
card	boolean | undefined	false	Wraps the value in a card container with border, padding, and shadow.
Details Declared type boolean | undefined Literal values false true Default value details Declaration false Source: packages/ui/src/components/counter/Counter.vue Resolved value false Source Counter.vue:35 packages/ui/src/components/counter/Counter.vue
valueStyle	CSSProperties | undefined	undefined	Inline styles applied to the wrapper around the value.
Details Declared type CSSProperties | undefined Default value details Declaration undefined Source: packages/ui/src/components/counter/Counter.vue Resolved value undefined Source Counter.vue:36 packages/ui/src/components/counter/Counter.vue
class	string | undefined	undefined	Classes added to the outer container in container mode, or to the number element when container mode is off.
Details Declared type string | undefined Default value details Declaration undefined Source: packages/ui/src/components/counter/Counter.vue Resolved value undefined Source Counter.vue:37 packages/ui/src/components/counter/Counter.vue

Counter — Events

Name	Signature or type	Description
@complete	[]	Emitted when the animation reaches to; it is also emitted when reduced-motion preferences cause the value to jump directly to the target.
Details Declared type [] Source Counter.vue packages/ui/src/components/counter/Counter.vue

Counter — Slots

Name	Signature or type	Description
#title	{}	Replaces the title prop content; providing this slot also enables container layout.
Details Declared type {} Source Counter.vue packages/ui/src/components/counter/Counter.vue

Counter — Exposes

Name	Signature or type	Description
play	() => void	Cancels the current animation and restarts from from; under reduced-motion preferences it jumps directly to the target.
Details Declared type () => void Source Counter.vue:137 packages/ui/src/components/counter/Counter.vue
stop	() => void	Cancels the current animation and stops further value updates.
Details Declared type () => void Source Counter.vue:137 packages/ui/src/components/counter/Counter.vue

Accessibility

• ARIA Attributes: Number content is accessible to screen readers