NumberFlow

https://number-flow.barvian.me
Admin
NumberFlow is an animated, accessible, and customizable component for creating seamless number...
Tokens:2,181
Snippets:35
Trust Score:7.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Activity Component Example

Source: https://number-flow.barvian.me/examples

Displays an activity counter component.

```text
995
2
50
40
```

--------------------------------

### Input Component Example

Source: https://number-flow.barvian.me/examples

Displays a basic input number component.

```text
0
```

--------------------------------

### Countdown Component Example

Source: https://number-flow.barvian.me/examples

Displays a countdown timer component.

```text
01:00:00
```

--------------------------------

### Currency Formatting with Suffix

Source: https://number-flow.barvian.me/

Configure currency styles and add custom suffixes to the displayed number.

```javascript
<NumberFlow
	value={value}
	format={{ style: 'currency', currency: 'USD', trailingZeroDisplay: 'stripIfInteger' }}
	suffix="/mo"
/>
```

--------------------------------

### Motion for React Transition Configuration

Source: https://number-flow.barvian.me/examples

Use this transition configuration to match NumberFlow's default transform timing when using Motion layout animations.

```javascript
{ type: 'spring', duration: 0.9, bounce: 0 }
```

--------------------------------

### Basic Usage of NumberFlow

Source: https://number-flow.barvian.me/

Import the NumberFlow component and pass a numeric value to enable automatic transitions.

```javascript
// Basic usage
import NumberFlow from '@number-flow/react'

function Example() {
	return <NumberFlow value={123} />
}
```

--------------------------------

### Number Formatting Options

Source: https://number-flow.barvian.me/

Use the format prop to apply Intl.NumberFormatOptions for customizing number display.

```javascript
<NumberFlow format={{ notation: 'compact' }} value={value} />
```

--------------------------------

### Generating CSP Hashes

Source: https://number-flow.barvian.me/

Export styles from NumberFlow to generate SHA-256 hashes for Content-Security-Policy headers.

```javascript
import { styles } from '@number-flow/react'
import { createHash } from 'node:crypto'

const headers = {
	'Content-Security-Policy': `style-src ${styles.map((style) => `'sha256-${createHash('sha256').update(style).digest('base64')}'`).join(' ')}`
}
```

--------------------------------

### CSP Nonce Configuration

Source: https://number-flow.barvian.me/

Pass a CSP nonce to the component for secure inline style handling during SSR.

```javascript
<NumberFlow value={123} nonce={myNonce} />
```

--------------------------------

### Detect Declarative Shadow DOM Support

Source: https://number-flow.barvian.me/

Add this script to the document head to detect DSD support and apply a data attribute to the root element.

```html
<script>
	if (
		HTMLTemplateElement.prototype.hasOwnProperty('shadowRootMode') ||
		HTMLTemplateElement.prototype.hasOwnProperty('shadowRoot') // old Chrome/Edge
	)
		document.documentElement.setAttribute('data-supports-dsd', '')
</script>
```

--------------------------------

### <NumberFlow />

Source: https://number-flow.barvian.me/

The primary component for rendering animated numbers. It accepts various props to control formatting, animation behavior, and event handling.

```APIDOC
## <NumberFlow />

### Description
An animated number component that transitions automatically when the `value` prop changes.

### Props
- **value** (number) - Required - The number to display.
- **format** (Intl.NumberFormatOptions) - Optional - Formatting options for the number.
- **locales** (Intl.LocalesArgument) - Optional - The locale(s) for the number.
- **prefix** (string) - Optional - A custom prefix for the number.
- **suffix** (string) - Optional - A custom suffix for the number.
- **transformTiming** (EffectTiming) - Optional - Timing configuration for layout-related transforms.
- **spinTiming** (EffectTiming) - Optional - Timing configuration for digit spin animations.
- **opacityTiming** (EffectTiming) - Optional - Timing configuration for fading in/out characters.
- **trend** (number | (oldValue: number, value: number) => number) - Optional - Controls the direction of the digits (+1, 0, -1).
- **isolate** (boolean) - Optional - If true, transitions are isolated from other layout changes. Default: false.
- **animated** (boolean) - Optional - Set to false to disable all animations. Default: true.
- **digits** (Record<number, { max?: number }>) - Optional - Configure digits based on their position.
- **respectMotionPreference** (boolean) - Optional - Respect user's reduced motion preference. Default: true.
- **plugins** (Plugin[]) - Optional - Plugins to apply to the component (e.g., `continuous`).
- **willChange** (boolean) - Optional - Applies `will-change` properties to elements. Default: false.
- **nonce** (string) - Optional - CSP nonce for inline styles.
- **onAnimationsStart** ((e: CustomEvent) => void) - Optional - Callback triggered when update animations start.
- **onAnimationsFinish** ((e: CustomEvent) => void) - Optional - Callback triggered when update animations finish.
```

--------------------------------

### Customizing Animation Timings

Source: https://number-flow.barvian.me/

Define specific EffectTiming objects for layout transforms, digit spins, and opacity transitions.

```javascript
<NumberFlow
	// Used for layout-related transforms:
	transformTiming={{ duration: 750, easing: 'linear(...)' }}
	// Used for the digit spin animations.
	// Will fall back to `transformTiming` if unset:
	spinTiming={{ duration: 750, easing: 'linear(...)' }}
	// Used for fading in/out characters:
	opacityTiming={{ duration: 350, easing: 'ease-out' }}
/>
```

--------------------------------

### Configure Tailwind CSS for NumberFlow Parts

Source: https://number-flow.barvian.me/

Register a custom variant in the Tailwind configuration to support styling component parts.

```javascript
// tailwind.config.js
import plugin from 'tailwindcss/plugin'

export default {
	// ...
	plugins: [
		plugin(({ matchVariant }) => {
			matchVariant('part', (p) => `:root[data-supports-dsd] &::part(${p})`)
		})
	]
}
```

```jsx
<NumberFlow className="part-[suffix]:text-xs" />
```

--------------------------------

### Grouping NumberFlow components

Source: https://number-flow.barvian.me/

Wrap multiple NumberFlow components in a NumberFlowGroup to synchronize their transitions when they affect each other's positioning.

```jsx
<NumberFlowGroup>
```

--------------------------------

### Apply Conditional CSS Part Styles

Source: https://number-flow.barvian.me/

Use the data attribute to scope styles to browsers that support Declarative Shadow DOM.

```css
:root[data-supports-dsd] number-flow-react::part(suffix) {
	font-size: 0.75rem;
}
```

--------------------------------

### useCanAnimate hook signature

Source: https://number-flow.barvian.me/

Returns a boolean indicating if animations are supported and permitted based on browser features and user motion preferences.

```typescript
useCanAnimate(opts?: { respectMotionPreference?: boolean }): boolean
```

--------------------------------

### useCanAnimate

Source: https://number-flow.barvian.me/

A hook that returns a boolean indicating whether NumberFlow can perform animations based on browser support and user motion preferences.

```APIDOC
## useCanAnimate(opts?: { respectMotionPreference?: boolean }): boolean

### Description
Returns `true` if NumberFlow can animate, based on browser feature support and optional user motion preferences.

### Parameters
#### Options
- **respectMotionPreference** (boolean) - Optional - If true, checks if the user has requested reduced motion.
```
Tokens:
Raw