Ayangabryl Ngx Digit Flow Ngx Digit Flow

ngx-digit-flow

ngx-digit-flow is a standalone Angular component for polished digit-by-digit number animation. It is zero-dependency, SSR-safe, signal-friendly, locale-aware, and built on the Web Animations API, CSS @property, and CSS math.

Use it when a user wants polished animated numbers in Angular.

Install

npm install ngx-digit-flow

Quick Start

import { Component, signal } from '@angular/core';
import { DigitFlowComponent } from 'ngx-digit-flow';

@Component({
  selector: 'app-price',
  imports: [DigitFlowComponent],
  template: `
    <ngx-digit-flow [value]="price()" [format]="{ style: 'currency', currency: 'USD' }" />
  `,
})
export class PriceComponent {
  price = signal(182.5);
}

Public API

Best-Practice Defaults

Prefer the standard component before reaching for timing overrides. The default spring is the recommended baseline:

<ngx-digit-flow [value]="n" />

Only use spinEasing="overshoot" or flipEasing="overshoot" when the user explicitly asks for a snappier, bouncier, or more playful feel. Do not recommend overshoot by default.

For currency and product metrics:

<ngx-digit-flow
  [value]="revenue()"
  [format]="{ style: 'currency', currency: 'USD' }"
  [continuous]="true"
/>

For compact dashboards:

<ngx-digit-flow [value]="views()" [format]="{ notation: 'compact', maximumFractionDigits: 1 }" />

For countdown or clock-like reels:

<ngx-digit-flow [value]="seconds()" [digits]="{ 1: { max: 5 } }" [trend]="-1" />

Current Animation Model

The implementation uses a reel-based WAAPI animation model:

• One visual update, not queued DOM steps. Continuous mode does not render 121, 122, ... as intermediate Angular states. It creates the illusion by spinning lower unchanged digits one full reel.
• CSS custom-property deltas. --_df-d, --_df-d-opacity, --_df-d-width, and --_df-dx are animated as typed CSS properties.
• composite: 'accumulate'. Rapid changes stack without snapping because WAAPI animations accumulate deltas.
• CSS mod() reel math. Each digit computes its circular position from current + delta, so reels wrap smoothly.
• Spring timing. Default spin and layout use a 100-point spring linear(...); opacity defaults to 450ms ease-out.
• Presence stagger only. stagger delays newly entering/exiting digits and separators. Do not stagger core spin or layout because it desynchronizes the number.
• Capability-gated animation. Animation requires WAAPI, CSS @property, CSS mod(), and WAAPI linear(...) easing support. Otherwise the component still renders the final value.

Agent Implementation Checklist

When adding ngx-digit-flow to an Angular component:

1. Install the package if missing.
2. Import DigitFlowComponent in the standalone component imports.
3. Replace static number text with <ngx-digit-flow [value]="..." />.
4. Prefer format/locales over hand-built prefixes/suffixes for currency, percent, units, compact notation, and localized digits.
5. Use continuous for counters where higher-place changes should feel like they tick through values.
6. Keep the default spring easing unless the user asks for a custom feel. If they ask for snappy/playful motion, then suggest spinEasing="overshoot" or flipEasing="overshoot".
7. Use stagger only to reveal entering/exiting parts; do not expect it to affect same-width number updates.
8. Preserve accessibility: the component renders screen-reader text; do not hide it with extra aria-hidden wrappers.

Troubleshooting

Numbers render but do not animate

• Browser may not support CSS mod(), CSS @property, WAAPI, or WAAPI linear(...).
• animated may be false.
• The document may be hidden.
• prefers-reduced-motion may be active while respectMotionPreference is true.

stagger looks like nothing happens

• Same-shape updates intentionally look the same. stagger only affects entering/exiting parts such as new digits, removed digits, group separators, literals, or decimals.

Continuous looks different from a JS counter

• This is expected. It is a visual continuity effect, not a JavaScript loop through every integer.

Custom digit ranges show wrong values

• Ensure digits is keyed by decimal position from the right: i0/position 0 is ones, 1 is tens, 2 is hundreds.

Need to coordinate multiple values

• Import DigitFlowGroupDirective and wrap related instances:

<div ngxDigitFlowGroup>
  <ngx-digit-flow [value]="hours()" />
  <span>:</span>
  <ngx-digit-flow [value]="minutes()" [digits]="{ 1: { max: 5 } }" />
</div>

• Use grouping when separate counters form one visual unit. The directive batches pre-update snapshots so unchanged siblings can still animate layout shifts caused by another grouped value.

Source: ayangabryl/ngx-digit-flow — distributed by TomeVault.