Counters

# Brok UI: Counter Number (`counter-number`)

An animated number that counts up to a target with grouped thousands when scrolled into view, respecting reduced-motion.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add counter-number
```

## Usage

```blade
<div class="flex flex-wrap gap-10">
    <div class="text-center">
        <x-ui.counter-number :value="1280" suffix="+" class="text-4xl font-bold" />
        <p class="mt-1 text-sm text-muted-foreground">Projects shipped</p>
    </div>
    <div class="text-center">
        <x-ui.counter-number :value="98" suffix="%" class="text-4xl font-bold" />
        <p class="mt-1 text-sm text-muted-foreground">Client satisfaction</p>
    </div>
    <div class="text-center">
        <x-ui.counter-number :value="24" prefix="$" suffix="M" class="text-4xl font-bold" />
        <p class="mt-1 text-sm text-muted-foreground">Revenue generated</p>
    </div>
</div>
```

## Props

- `value` (int, default `0`) — Target number the counter animates to.
- `from` (int, default `0`) — Starting number the counter animates from.
- `duration` (int, default `2000`) — Animation duration in milliseconds.
- `decimals` (int, default `0`) — Number of decimal places shown while formatting.
- `prefix` (string, default ``) — Text prepended to the formatted number, such as a currency symbol.
- `suffix` (string, default ``) — Text appended to the formatted number, such as a unit or percent sign.
- `once` (bool, default `true`) — Whether the count-up plays only the first time it scrolls into view.

## Use when

- Use to summarize, sequence, or present data so users can scan it quickly.
- Drawing attention to a KPI or stat that should animate up from a starting value when it appears.
- Formatting a number with a prefix, suffix, or fixed decimal places while it counts.

## Avoid when

- Do not add display-only ornament when the user needs actionable structure or exact comparison instead.
- The value changes repeatedly after mount; use number-flow, which is built for recurring value transitions.

## Anti-patterns

- Adding display ornament without informational value

## Rules

- Use the `<brok:counter-number>` tag (or `<x-ui.counter-number>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/counter-number
- Registry JSON (files, props, contract): https://brokui.dev/r/open/counter-number.json

@props([
    'value' => 0,
    'from' => 0,
    'duration' => 2000,
    'decimals' => 0,
    'prefix' => '',
    'suffix' => '',
    'once' => true,
])

@php
    // Coerce numeric props once so SSR and the JS config stay in lock-step.
    $valueNum = (float) $value;
    $fromNum = (float) $from;
    $decimalsNum = (int) $decimals;

    $config = [
        'value' => $valueNum,
        'from' => $fromNum,
        'duration' => (int) $duration,
        'decimals' => $decimalsNum,
        'prefix' => (string) $prefix,
        'suffix' => (string) $suffix,
        'once' => (bool) $once,
    ];
@endphp

<span
    data-slot="counter-number"
    x-data="uiCounterNumber(@js($config))"
    x-text="formatted"
    {{ $attributes->merge(['class' => 'tabular-nums text-foreground']) }}
>{{ $prefix }}{{ number_format($valueNum, $decimalsNum) }}{{ $suffix }}</span>

/**
 * Counter Number behavior.
 *
 * Animates a number from `from` to `value` with an ease-out curve once the
 * element scrolls into view (via IntersectionObserver). The formatted output
 * uses grouped thousands separators so it matches the SSR `number_format`
 * fallback rendered in the Blade. Honors reduced-motion by jumping straight to
 * the final value. Self-registers on `alpine:init`.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiCounterNumber', (config = {}) => ({
        value: config.value ?? 0,
        from: config.from ?? 0,
        duration: config.duration ?? 2000,
        decimals: config.decimals ?? 0,
        prefix: config.prefix ?? '',
        suffix: config.suffix ?? '',
        once: config.once ?? true,

        current: 0,
        _observer: null,
        _raf: null,

        init() {
            this.current = this.from;

            // Reduced motion: show the final value immediately, no animation.
            if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
                this.current = this.value;
                return;
            }

            this._observer = new IntersectionObserver((entries) => {
                entries.forEach((entry) => {
                    if (entry.isIntersecting) {
                        this.animate();
                        if (this.once) {
                            this._observer.disconnect();
                            this._observer = null;
                        }
                    }
                });
            });
            this._observer.observe(this.$el);
        },

        animate() {
            if (this._raf) {
                cancelAnimationFrame(this._raf);
            }

            const start = performance.now();
            const startVal = this.from;
            const delta = this.value - startVal;

            const step = (now) => {
                const elapsed = now - start;
                const t = this.duration > 0 ? Math.min(1, elapsed / this.duration) : 1;
                // Ease-out expo: fast through the big numbers, a long soft
                // landing on the last few — the odometer feel.
                const eased = t >= 1 ? 1 : 1 - Math.pow(2, -10 * t);
                this.current = startVal + delta * eased;

                if (t < 1) {
                    this._raf = requestAnimationFrame(step);
                } else {
                    this.current = this.value;
                    this._raf = null;
                }
            };

            this._raf = requestAnimationFrame(step);
        },

        get formatted() {
            return this.prefix + this.formatNumber(this.current) + this.suffix;
        },

        // Group thousands with commas to mirror PHP number_format().
        formatNumber(n) {
            const fixed = Number(n).toFixed(this.decimals);
            const [intPart, decPart] = fixed.split('.');
            const sign = intPart.startsWith('-') ? '-' : '';
            const digits = sign ? intPart.slice(1) : intPart;
            const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
            return sign + grouped + (decPart ? '.' + decPart : '');
        },

        destroy() {
            if (this._observer) {
                this._observer.disconnect();
                this._observer = null;
            }
            if (this._raf) {
                cancelAnimationFrame(this._raf);
                this._raf = null;
            }
        },
    }));
});