# Number Ticker

Angka yang berhitung naik ke nilainya saat masuk layar, dengan pemisah ribuan, desimal, serta prefix atau suffix.

- Kategori: Animasi
- Status: stable
- Registry: https://markas.jenderalcorp.com/r/number-ticker.json
- CLI: `npx markasui@latest add number-ticker`

## Kapan dipakai

Menonjolkan statistik di landing page atau kartu dashboard saat masuk layar.

- Atur ukuran dan ketebalan teks di elemen induk; ticker mewarisinya
- Pakai prefix dan suffix untuk mata uang dan satuan, jangan ditulis di samping komponen
- Pakai untuk beberapa angka penting, bukan setiap nilai di tabel
- Blade butuh Alpine.js

## Kode

### Blade

Simpan di `resources/views/components/markas/number-ticker.blade.php`. Dependensi: alpinejs.

```blade
@props([
    'value' => 0,
    'from' => 0,
    'duration' => 2000,
    'decimals' => 0,
    'locale' => 'en-US',
    'prefix' => '',
    'suffix' => '',
])

@php
    $root = 'inline-grid tabular-nums';
    $layer = 'col-start-1 row-start-1';
    $holder = 'invisible col-start-1 row-start-1';

    // Teks awal sebelum Alpine berjalan. Alpine memformat ulang dengan Intl.NumberFormat sesuai locale.
    $initial = $prefix.number_format((float) $value, (int) $decimals).$suffix;
@endphp

<span
    x-data="{
        value: @js((float) $value),
        display: @js((float) $value),
        current: @js((float) $from),
        frame: 0,
        observer: null,
        {{-- Built once: text() runs on every frame and on every Livewire re-render. --}}
        formatter: new Intl.NumberFormat(@js($locale), { minimumFractionDigits: @js((int) $decimals), maximumFractionDigits: @js((int) $decimals) }),
        text(n) {
            return @js($prefix) + this.formatter.format(n) + @js($suffix);
        },
        {{-- Hitung dari angka awal ke value dengan ease-out eksponensial saat elemen pertama kali terlihat. --}}
        run() {
            const start = this.current;
            let began;
            const tick = (now) => {
                began ??= now;
                const progress = Math.min((now - began) / @js((int) $duration), 1);
                this.current = start + (this.value - start) * (progress >= 1 ? 1 : 1 - 2 ** (-10 * progress));
                this.display = this.current;
                if (progress < 1) this.frame = requestAnimationFrame(tick);
            };
            this.frame = requestAnimationFrame(tick);
        },
        init() {
            if (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return;
            this.display = this.current;
            if (typeof IntersectionObserver === 'undefined') return this.run();
            this.observer = new IntersectionObserver((entries) => {
                if (! entries.some((entry) => entry.isIntersecting)) return;
                this.observer.disconnect();
                this.run();
            });
            this.observer.observe(this.$el);
        },
        destroy() {
            this.observer?.disconnect();
            cancelAnimationFrame(this.frame);
        },
    }"
    {{ $attributes->class([$root]) }}
><span class="sr-only" x-text="text(value)">{{ $initial }}</span><span aria-hidden="true" class="{{ $holder }}" x-text="text(value)">{{ $initial }}</span><span aria-hidden="true" class="{{ $layer }}" x-text="text(display)">{{ $initial }}</span></span>
```

```blade
<p class="text-4xl font-semibold">
    <x-markas.number-ticker :value="84200000" prefix="Rp" locale="id-ID" />
</p>
<x-markas.number-ticker :value="99.9" :decimals="1" suffix="%" locale="id-ID" />
<x-markas.number-ticker :value="12" :from="100" />
```

### React

Simpan di `src/components/markas/NumberTicker.tsx`. Tanpa dependensi tambahan.

```tsx
"use client";

import { useEffect, useRef, useState, type ComponentProps } from "react";

const root = "inline-grid tabular-nums";
const layer = "col-start-1 row-start-1";
const holder = "invisible col-start-1 row-start-1";

const cx = (...c: (string | false | null | undefined)[]) =>
  c.filter(Boolean).join(" ");

const reducedMotion = () =>
  typeof matchMedia === "function" &&
  matchMedia("(prefers-reduced-motion: reduce)").matches;

/** Ease-out eksponensial: cepat di awal, melambat menjelang angka akhir. */
const easeOut = (t: number) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t));

/** Panggil `callback` sekali saat elemen pertama kali terlihat. Mengembalikan fungsi pelepas. */
function whenVisible(element: Element, callback: () => void) {
  if (typeof IntersectionObserver === "undefined") {
    callback();
    return () => {};
  }
  const observer = new IntersectionObserver((entries) => {
    if (!entries.some((entry) => entry.isIntersecting)) return;
    observer.disconnect();
    callback();
  });
  observer.observe(element);
  return () => observer.disconnect();
}

export type NumberTickerProps = Omit<ComponentProps<"span">, "children"> & {
  value: number;
  from?: number;
  duration?: number;
  decimals?: number;
  locale?: string;
  prefix?: string;
  suffix?: string;
};

export function NumberTicker({
  value,
  from = 0,
  duration = 2000,
  decimals = 0,
  locale = "en-US",
  prefix = "",
  suffix = "",
  className,
  ...props
}: NumberTickerProps) {
  const rootRef = useRef<HTMLSpanElement>(null);
  const current = useRef(from);
  const [display, setDisplay] = useState(value);

  useEffect(() => {
    const element = rootRef.current;
    if (!element || reducedMotion()) {
      current.current = value;
      setDisplay(value);
      return;
    }
    const start = current.current;
    let frame = 0;
    setDisplay(start);
    const stop = whenVisible(element, () => {
      let began: number | undefined;
      const tick = (now: number) => {
        began ??= now;
        const progress = Math.min((now - began) / duration, 1);
        current.current = start + (value - start) * easeOut(progress);
        setDisplay(current.current);
        if (progress < 1) frame = requestAnimationFrame(tick);
      };
      frame = requestAnimationFrame(tick);
    });
    return () => {
      stop();
      cancelAnimationFrame(frame);
    };
  }, [value, duration]);

  const formatter = new Intl.NumberFormat(locale, {
    minimumFractionDigits: decimals,
    maximumFractionDigits: decimals,
  });
  const text = (n: number) => `${prefix}${formatter.format(n)}${suffix}`;

  return (
    <span ref={rootRef} {...props} className={cx(root, className)}>
      <span className="sr-only">{text(value)}</span>
      <span aria-hidden="true" className={holder}>
        {text(value)}
      </span>
      <span aria-hidden="true" className={layer}>
        {text(display)}
      </span>
    </span>
  );
}
```

```tsx
import { NumberTicker } from "@/components/markas/NumberTicker";

<p className="text-4xl font-semibold">
  <NumberTicker value={84200000} prefix="Rp" locale="id-ID" />
</p>
<NumberTicker value={99.9} decimals={1} suffix="%" locale="id-ID" />
<NumberTicker value={12} from={100} />
```

### Vue

Simpan di `src/components/markas/NumberTicker.vue`. Tanpa dependensi tambahan.

```vue
<script setup lang="ts">
import {
  computed,
  onBeforeUnmount,
  onMounted,
  ref,
  useTemplateRef,
  watch,
} from "vue";

const props = withDefaults(
  defineProps<{
    value: number;
    from?: number;
    duration?: number;
    decimals?: number;
    locale?: string;
    prefix?: string;
    suffix?: string;
  }>(),
  {
    from: 0,
    duration: 2000,
    decimals: 0,
    locale: "en-US",
    prefix: "",
    suffix: "",
  },
);

const root = "inline-grid tabular-nums";
const layer = "col-start-1 row-start-1";
const holder = "invisible col-start-1 row-start-1";

const reducedMotion = () =>
  typeof matchMedia === "function" &&
  matchMedia("(prefers-reduced-motion: reduce)").matches;

/** Ease-out eksponensial: cepat di awal, melambat menjelang angka akhir. */
const easeOut = (t: number) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t));

/** Panggil `callback` sekali saat elemen pertama kali terlihat. Mengembalikan fungsi pelepas. */
function whenVisible(element: Element, callback: () => void) {
  if (typeof IntersectionObserver === "undefined") {
    callback();
    return () => {};
  }
  const observer = new IntersectionObserver((entries) => {
    if (!entries.some((entry) => entry.isIntersecting)) return;
    observer.disconnect();
    callback();
  });
  observer.observe(element);
  return () => observer.disconnect();
}

const rootEl = useTemplateRef<HTMLSpanElement>("rootRef");
const display = ref(props.value);
let current = props.from;
let frame = 0;
let stop = () => {};

function cancel() {
  stop();
  cancelAnimationFrame(frame);
}

function run() {
  cancel();
  const element = rootEl.value;
  if (!element || reducedMotion()) {
    current = props.value;
    display.value = props.value;
    return;
  }
  const start = current;
  const target = props.value;
  display.value = start;
  stop = whenVisible(element, () => {
    let began: number | undefined;
    const tick = (now: number) => {
      began ??= now;
      const progress = Math.min((now - began) / props.duration, 1);
      current = start + (target - start) * easeOut(progress);
      display.value = current;
      if (progress < 1) frame = requestAnimationFrame(tick);
    };
    frame = requestAnimationFrame(tick);
  });
}

onMounted(run);
watch(() => [props.value, props.duration], run);
onBeforeUnmount(cancel);

const formatter = computed(
  () =>
    new Intl.NumberFormat(props.locale, {
      minimumFractionDigits: props.decimals,
      maximumFractionDigits: props.decimals,
    }),
);
const text = (n: number) =>
  `${props.prefix}${formatter.value.format(n)}${props.suffix}`;
</script>

<template>
  <span ref="rootRef" :class="root"
    ><span class="sr-only">{{ text(props.value) }}</span
    ><span aria-hidden="true" :class="holder">{{ text(props.value) }}</span
    ><span aria-hidden="true" :class="layer">{{ text(display) }}</span></span
  >
</template>
```

```vue
<template>
  <p class="text-4xl font-semibold">
    <NumberTicker :value="84200000" prefix="Rp" locale="id-ID" />
  </p>
  <NumberTicker :value="99.9" :decimals="1" suffix="%" locale="id-ID" />
  <NumberTicker :value="12" :from="100" />
</template>
```

### Svelte

Simpan di `src/lib/components/markas/NumberTicker.svelte`. Tanpa dependensi tambahan.

```svelte
<script lang="ts">
  import { untrack } from "svelte";
  import type { HTMLAttributes } from "svelte/elements";

  const root = "inline-grid tabular-nums";
  const layer = "col-start-1 row-start-1";
  const holder = "invisible col-start-1 row-start-1";

  const reducedMotion = () =>
    typeof matchMedia === "function" &&
    matchMedia("(prefers-reduced-motion: reduce)").matches;

  /** Exponential ease-out: fast at first, slowing down near the final number. */
  const easeOut = (t: number) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t));

  /** Calls `callback` once, the first time the element is visible. Returns a cleanup function. */
  function whenVisible(element: Element, callback: () => void) {
    if (typeof IntersectionObserver === "undefined") {
      callback();
      return () => {};
    }
    const observer = new IntersectionObserver((entries) => {
      if (!entries.some((entry) => entry.isIntersecting)) return;
      observer.disconnect();
      callback();
    });
    observer.observe(element);
    return () => observer.disconnect();
  }

  type Props = Omit<HTMLAttributes<HTMLSpanElement>, "children" | "prefix"> & {
    value: number;
    from?: number;
    /** Milliseconds from the start number to value. */
    duration?: number;
    decimals?: number;
    locale?: string;
    prefix?: string;
    suffix?: string;
  };

  let {
    value,
    from = 0,
    duration = 2000,
    decimals = 0,
    locale = "en-US",
    prefix = "",
    suffix = "",
    class: className,
    ...rest
  }: Props = $props();

  let element = $state<HTMLSpanElement>();
  // The number the animation last reached; the next run starts from here.
  let current = untrack(() => from);
  let display = $state(untrack(() => value));

  $effect(() => {
    const target = value;
    const ms = duration;
    if (!element || reducedMotion()) {
      current = target;
      display = target;
      return;
    }
    const start = current;
    let frame = 0;
    display = start;
    const stop = whenVisible(element, () => {
      let began: number | undefined;
      const tick = (now: number) => {
        began ??= now;
        const progress = Math.min((now - began) / ms, 1);
        current = start + (target - start) * easeOut(progress);
        display = current;
        if (progress < 1) frame = requestAnimationFrame(tick);
      };
      frame = requestAnimationFrame(tick);
    });
    return () => {
      stop();
      cancelAnimationFrame(frame);
    };
  });

  const formatter = $derived(
    new Intl.NumberFormat(locale, {
      minimumFractionDigits: decimals,
      maximumFractionDigits: decimals,
    }),
  );
  const text = (n: number) => `${prefix}${formatter.format(n)}${suffix}`;
</script>

<span bind:this={element} {...rest} class={[root, className]}
  ><span class="sr-only">{text(value)}</span><span
    aria-hidden="true"
    class={holder}>{text(value)}</span
  ><span aria-hidden="true" class={layer}>{text(display)}</span></span
>
```

```svelte
<script lang="ts">
  import NumberTicker from "$lib/components/markas/NumberTicker.svelte";
</script>

<p class="text-4xl font-semibold">
  <NumberTicker value={84200} prefix="$" />
</p>
<NumberTicker value={99.9} decimals={1} suffix="%" />
```

### Astro

Simpan di `src/components/markas/NumberTicker.astro`. Tanpa dependensi tambahan.

```astro
---
import type { HTMLAttributes } from "astro/types";

const root = "inline-grid tabular-nums";
const layer = "col-start-1 row-start-1";
const holder = "invisible col-start-1 row-start-1";

type Props = Omit<HTMLAttributes<"span">, "prefix"> & {
  value: number;
  from?: number;
  /** Milliseconds from the start number to value. */
  duration?: number;
  decimals?: number;
  locale?: string;
  prefix?: string;
  suffix?: string;
};

const {
  value,
  from = 0,
  duration = 2000,
  decimals = 0,
  locale = "en-US",
  prefix = "",
  suffix = "",
  class: className,
  ...rest
} = Astro.props;
const formatter = new Intl.NumberFormat(locale, {
  minimumFractionDigits: decimals,
  maximumFractionDigits: decimals,
});
// The final number is rendered on the server; the script counts up to it once it is visible.
const text = `${prefix}${formatter.format(value)}${suffix}`;
---

<markas-number-ticker
  class="contents"
  data-value={value}
  data-from={from}
  data-duration={duration}
  data-decimals={decimals}
  data-locale={locale}
  data-prefix={prefix}
  data-suffix={suffix}
><span {...rest} class:list={[root, className]}><span class="sr-only">{text}</span><span aria-hidden="true" class={holder}>{text}</span><span aria-hidden="true" class={layer}>{text}</span></span></markas-number-ticker>

<script>
  /** Exponential ease-out: fast at first, slowing down near the final number. */
  const easeOut = (t: number) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t));

  // One element per ticker: setup runs for markup added later and after view transitions.
  class MarkasNumberTicker extends HTMLElement {
    private cleanup = () => {};

    connectedCallback() {
      const display = this.firstElementChild?.lastElementChild;
      if (!display || matchMedia("(prefers-reduced-motion: reduce)").matches)
        return;
      const data = this.dataset;
      const decimals = Number(data.decimals);
      const formatter = new Intl.NumberFormat(data.locale, {
        minimumFractionDigits: decimals,
        maximumFractionDigits: decimals,
      });
      const show = (n: number) =>
        (display.textContent = `${data.prefix ?? ""}${formatter.format(n)}${data.suffix ?? ""}`);
      const start = Number(data.from);
      const target = Number(data.value);
      const duration = Number(data.duration);
      let frame = 0;
      show(start);
      // Count from the start number to value the first time the ticker is visible.
      const observer = new IntersectionObserver((entries) => {
        if (!entries.some((entry) => entry.isIntersecting)) return;
        observer.disconnect();
        let began: number | undefined;
        const tick = (now: number) => {
          began ??= now;
          const progress = Math.min((now - began) / duration, 1);
          show(start + (target - start) * easeOut(progress));
          if (progress < 1) frame = requestAnimationFrame(tick);
        };
        frame = requestAnimationFrame(tick);
      });
      observer.observe(this.firstElementChild!);
      this.cleanup = () => {
        observer.disconnect();
        cancelAnimationFrame(frame);
      };
    }

    disconnectedCallback() {
      this.cleanup();
    }
  }

  if (!customElements.get("markas-number-ticker"))
    customElements.define("markas-number-ticker", MarkasNumberTicker);
</script>
```

```astro
---
import NumberTicker from "@/components/markas/NumberTicker.astro";
---

<p class="text-4xl font-semibold">
  <NumberTicker value={84200} prefix="$" />
</p>
<NumberTicker value={12} from={100} />
```

### Angular

Simpan di `src/app/markas/number-ticker.component.ts`. Tanpa dependensi tambahan.

```ts
import {
  afterRenderEffect,
  ChangeDetectionStrategy,
  Component,
  computed,
  ElementRef,
  inject,
  input,
  numberAttribute,
  linkedSignal,
  untracked,
} from "@angular/core";

const root = "inline-grid tabular-nums";
const layer = "col-start-1 row-start-1";
const holder = "invisible col-start-1 row-start-1";

const reducedMotion = () =>
  typeof matchMedia === "function" &&
  matchMedia("(prefers-reduced-motion: reduce)").matches;

/** Exponential ease-out: fast at first, slowing down near the final number. */
const easeOut = (t: number) => (t >= 1 ? 1 : 1 - 2 ** (-10 * t));

/** Calls `callback` once, the first time the element is visible. Returns a cleanup function. */
function whenVisible(element: Element, callback: () => void) {
  if (typeof IntersectionObserver === "undefined") {
    callback();
    return () => {};
  }
  const observer = new IntersectionObserver((entries) => {
    if (!entries.some((entry) => entry.isIntersecting)) return;
    observer.disconnect();
    callback();
  });
  observer.observe(element);
  return () => observer.disconnect();
}

/** Attribute selector on a span: class and other attributes stay on the root. */
@Component({
  selector: "span[markas-number-ticker]",
  changeDetection: ChangeDetectionStrategy.OnPush,
  host: { "[class]": "root" },
  template: `<span class="sr-only">{{ text(value()) }}</span
    ><span aria-hidden="true" [class]="holder">{{ text(value()) }}</span
    ><span aria-hidden="true" [class]="layer">{{ text(display()) }}</span>`,
})
export class NumberTicker {
  readonly value = input.required({ transform: numberAttribute });
  readonly from = input(0, { transform: numberAttribute });
  /** Milliseconds from the start number to value. */
  readonly duration = input(2000, { transform: numberAttribute });
  readonly decimals = input(0, { transform: numberAttribute });
  readonly locale = input("en-US");
  readonly prefix = input("");
  readonly suffix = input("");

  protected readonly root = root;
  protected readonly layer = layer;
  protected readonly holder = holder;
  // Starts at the final value, like the server render of the other versions.
  protected readonly display = linkedSignal(() => this.value());
  private readonly formatter = computed(
    () =>
      new Intl.NumberFormat(this.locale(), {
        minimumFractionDigits: this.decimals(),
        maximumFractionDigits: this.decimals(),
      }),
  );
  private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);
  /** The number the animation last reached; the next run starts from here. */
  private current: number | undefined;

  constructor() {
    afterRenderEffect((onCleanup) => {
      const target = this.value();
      const duration = this.duration();
      this.current ??= untracked(this.from);
      if (reducedMotion()) {
        this.current = target;
        this.display.set(target);
        return;
      }
      const start = this.current;
      let frame = 0;
      this.display.set(start);
      const stop = whenVisible(this.host.nativeElement, () => {
        let began: number | undefined;
        const tick = (now: number) => {
          began ??= now;
          const progress = Math.min((now - began) / duration, 1);
          this.current = start + (target - start) * easeOut(progress);
          this.display.set(this.current);
          if (progress < 1) frame = requestAnimationFrame(tick);
        };
        frame = requestAnimationFrame(tick);
      });
      onCleanup(() => {
        stop();
        cancelAnimationFrame(frame);
      });
    });
  }

  protected text(n: number) {
    return `${this.prefix()}${this.formatter().format(n)}${this.suffix()}`;
  }
}
```

```ts
import { Component } from "@angular/core";
import { NumberTicker } from "./markas/number-ticker.component";

@Component({
  selector: "app-revenue",
  imports: [NumberTicker],
  template: `
    <p class="text-4xl font-semibold">
      <span markas-number-ticker [value]="revenue" prefix="$"></span>
    </p>
    <span markas-number-ticker value="99.9" decimals="1" suffix="%"></span>
  `,
})
export class Revenue {
  revenue = 84200;
}
```

## Props

| Nama | Tipe | Default | Keterangan |
| --- | --- | --- | --- |
| `value` | `number` | - | Angka akhir. Kalau diubah kemudian, hitungan berjalan dari angka sekarang ke angka baru. |
| `from` | `number` | 0 | Angka awal. Isi lebih besar dari value untuk hitung mundur. |
| `duration` | `number` | 2000 | Lama hitungan dalam milidetik. |
| `decimals` | `number` | 0 | Jumlah angka di belakang koma yang ditampilkan. |
| `locale` | `string` | en-US | Locale untuk Intl.NumberFormat, misalnya id-ID agar pemisah ribuan memakai titik. |
| `prefix` | `string` | '' | Teks sebelum angka, misalnya Rp. |
| `suffix` | `string` | '' | Teks setelah angka, misalnya % atau +. |

## Aksesibilitas

- Screen reader membaca nilai akhir dari salinan tersembunyi; digit yang berhitung memakai aria-hidden.
- Salinan nilai akhir yang tidak terlihat menjaga lebar, jadi tata letak tidak bergeser saat berhitung.
- Dengan reduced motion, nilai akhir langsung tampil.

## Catatan

- Hitungan dimulai saat angka pertama kali masuk layar dan melambat menjelang akhir.
- Server merender nilai akhir, jadi angka tetap benar tanpa JavaScript dan untuk mesin pencari.
- Format memakai `Intl.NumberFormat` dengan `locale` (bawaan `en-US`). Isi `id-ID` agar pemisah ribuan berupa titik. Versi Blade butuh Alpine.js.
- Dengan reduced motion, nilai akhir langsung tampil.
