diff --git a/packages/react/src/components/number-flow/examples/with-timer.tsx b/packages/react/src/components/number-flow/examples/with-timer.tsx
new file mode 100644
index 0000000000..96ce67b635
--- /dev/null
+++ b/packages/react/src/components/number-flow/examples/with-timer.tsx
@@ -0,0 +1,41 @@
+import { NumberFlow } from '@ark-ui/react/number-flow'
+import { Timer, useTimer } from '@ark-ui/react/timer'
+import { PauseIcon, PlayIcon, RotateCcwIcon } from 'lucide-react'
+import button from 'styles/button.module.css'
+import styles from 'styles/number-flow.module.css'
+import timerStyles from 'styles/timer.module.css'
+
+const formatOptions = { minimumIntegerDigits: 2 }
+
+export const WithTimer = () => {
+ const timer = useTimer({ countdown: true, startMs: 5 * 60 * 1000 })
+
+ return (
+
+ Offer ends in
+
+
+
+
+ :
+
+
+
+
+
+
+ Start
+
+
+ Pause
+
+
+ Resume
+
+
+ Reset
+
+
+
+ )
+}
diff --git a/packages/react/src/components/number-flow/number-flow.stories.tsx b/packages/react/src/components/number-flow/number-flow.stories.tsx
index c798eeefcf..d938d59a0a 100644
--- a/packages/react/src/components/number-flow/number-flow.stories.tsx
+++ b/packages/react/src/components/number-flow/number-flow.stories.tsx
@@ -17,3 +17,4 @@ export { Pricing } from './examples/pricing.tsx'
export { RootProvider } from './examples/root-provider.tsx'
export { Timing } from './examples/timing.tsx'
export { Trend } from './examples/trend.tsx'
+export { WithTimer } from './examples/with-timer.tsx'
diff --git a/packages/solid/src/components/number-flow/examples/with-timer.tsx b/packages/solid/src/components/number-flow/examples/with-timer.tsx
new file mode 100644
index 0000000000..64701352ef
--- /dev/null
+++ b/packages/solid/src/components/number-flow/examples/with-timer.tsx
@@ -0,0 +1,41 @@
+import { NumberFlow } from '@ark-ui/solid/number-flow'
+import { Timer, useTimer } from '@ark-ui/solid/timer'
+import { PauseIcon, PlayIcon, RotateCcwIcon } from 'lucide-solid'
+import button from 'styles/button.module.css'
+import styles from 'styles/number-flow.module.css'
+import timerStyles from 'styles/timer.module.css'
+
+const formatOptions = { minimumIntegerDigits: 2 }
+
+export const WithTimer = () => {
+ const timer = useTimer({ countdown: true, startMs: 5 * 60 * 1000 })
+
+ return (
+
+ Offer ends in
+
+
+
+
+ :
+
+
+
+
+
+
+ Start
+
+
+ Pause
+
+
+ Resume
+
+
+ Reset
+
+
+
+ )
+}
diff --git a/packages/solid/src/components/number-flow/number-flow.stories.tsx b/packages/solid/src/components/number-flow/number-flow.stories.tsx
index db726b0767..b6dd074dff 100644
--- a/packages/solid/src/components/number-flow/number-flow.stories.tsx
+++ b/packages/solid/src/components/number-flow/number-flow.stories.tsx
@@ -17,3 +17,4 @@ export { Pricing } from './examples/pricing.tsx'
export { RootProvider } from './examples/root-provider.tsx'
export { Timing } from './examples/timing.tsx'
export { Trend } from './examples/trend.tsx'
+export { WithTimer } from './examples/with-timer.tsx'
diff --git a/packages/svelte/src/lib/components/number-flow/examples/with-timer.svelte b/packages/svelte/src/lib/components/number-flow/examples/with-timer.svelte
new file mode 100644
index 0000000000..02066445a6
--- /dev/null
+++ b/packages/svelte/src/lib/components/number-flow/examples/with-timer.svelte
@@ -0,0 +1,39 @@
+
+
+
+ Offer ends in
+
+
+
+
+ :
+
+
+
+
+
+
+ Start
+
+
+ Pause
+
+
+ Resume
+
+
+ Reset
+
+
+
diff --git a/packages/svelte/src/lib/components/number-flow/number-flow.stories.ts b/packages/svelte/src/lib/components/number-flow/number-flow.stories.ts
index b16785ea5e..2af963af44 100644
--- a/packages/svelte/src/lib/components/number-flow/number-flow.stories.ts
+++ b/packages/svelte/src/lib/components/number-flow/number-flow.stories.ts
@@ -10,6 +10,7 @@ import PricingExample from './examples/pricing.svelte'
import RootProviderExample from './examples/root-provider.svelte'
import TimingExample from './examples/timing.svelte'
import TrendExample from './examples/trend.svelte'
+import WithTimerExample from './examples/with-timer.svelte'
const meta = {
title: 'Components / Number Flow',
@@ -82,3 +83,9 @@ export const Trend = {
Component: TrendExample,
}),
}
+
+export const WithTimer = {
+ render: () => ({
+ Component: WithTimerExample,
+ }),
+}
diff --git a/packages/vue/src/components/number-flow/examples/with-timer.vue b/packages/vue/src/components/number-flow/examples/with-timer.vue
new file mode 100644
index 0000000000..d3ef773bdf
--- /dev/null
+++ b/packages/vue/src/components/number-flow/examples/with-timer.vue
@@ -0,0 +1,54 @@
+
+
+
+
+ Offer ends in
+
+
+
+
+ :
+
+
+
+
+
+
+
+ Start
+
+
+
+ Pause
+
+
+
+ Resume
+
+
+
+ Reset
+
+
+
+
diff --git a/packages/vue/src/components/number-flow/number-flow.stories.ts b/packages/vue/src/components/number-flow/number-flow.stories.ts
index 4ce479d12a..0acd816ff4 100644
--- a/packages/vue/src/components/number-flow/number-flow.stories.ts
+++ b/packages/vue/src/components/number-flow/number-flow.stories.ts
@@ -11,6 +11,7 @@ import PricingExample from './examples/pricing.vue'
import RootProviderExample from './examples/root-provider.vue'
import TimingExample from './examples/timing.vue'
import TrendExample from './examples/trend.vue'
+import WithTimerExample from './examples/with-timer.vue'
const meta: Meta = {
title: 'Components / Number Flow',
@@ -94,3 +95,10 @@ export const Trend = {
template: '',
}),
}
+
+export const WithTimer = {
+ render: () => ({
+ components: { Component: WithTimerExample },
+ template: '',
+ }),
+}
diff --git a/packages/web/examples/number-flow/with-timer.ts b/packages/web/examples/number-flow/with-timer.ts
new file mode 100644
index 0000000000..bac3dfb55e
--- /dev/null
+++ b/packages/web/examples/number-flow/with-timer.ts
@@ -0,0 +1,56 @@
+import { createElement, Pause, Play, RotateCcw } from 'lucide'
+
+import '@ark-ui/web/number-flow'
+import '@ark-ui/web/timer'
+
+import button from 'styles/button.module.css'
+import styles from 'styles/number-flow.module.css'
+import timerStyles from 'styles/timer.module.css'
+
+const icon = (node: typeof Play) => createElement(node, { 'aria-hidden': 'true' }).outerHTML
+
+const flow = (unit: string) => /* html */ `
+
+
+ `
+
+export function mount(root: HTMLElement) {
+ root.innerHTML = /* html */ `
+
+ Offer ends in
+
+ ${flow('minutes')}
+ :
+ ${flow('seconds')}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ `
+
+ const timer = root.querySelector('ark-timer')!
+ const flows = root.querySelectorAll('ark-number-flow')
+
+ for (const el of flows) el.formatOptions = { minimumIntegerDigits: 2 }
+
+ const sync = () => {
+ const time = timer.api?.time
+ if (!time) return
+ for (const el of flows) el.value = time[el.dataset.unit as 'minutes' | 'seconds']
+ }
+
+ timer.addEventListener('tick', sync)
+ root.querySelector('ark-timer-control')!.addEventListener('click', () => queueMicrotask(sync))
+ timer.ready.then(sync)
+}
diff --git a/packages/web/src/components/number-flow/number-flow.stories.ts b/packages/web/src/components/number-flow/number-flow.stories.ts
index 8ca252e06b..a3a8f0ef3a 100644
--- a/packages/web/src/components/number-flow/number-flow.stories.ts
+++ b/packages/web/src/components/number-flow/number-flow.stories.ts
@@ -7,6 +7,7 @@ import { mount as LiveExample } from '../../../examples/number-flow/live.js'
import { mount as LocaleExample } from '../../../examples/number-flow/locale.js'
import { mount as PrefixSuffixExample } from '../../../examples/number-flow/prefix-suffix.js'
import { mount as TimingExample } from '../../../examples/number-flow/timing.js'
+import { mount as WithTimerExample } from '../../../examples/number-flow/with-timer.js'
const meta: Meta = { title: 'Components / Number Flow' }
export default meta
@@ -24,3 +25,5 @@ export const Locale: StoryObj = { name: 'Locale', render: renderExample(LocaleEx
export const PrefixSuffix: StoryObj = { name: 'Prefix Suffix', render: renderExample(PrefixSuffixExample) }
export const Timing: StoryObj = { name: 'Timing', render: renderExample(TimingExample) }
+
+export const WithTimer: StoryObj = { name: 'With Timer', render: renderExample(WithTimerExample) }
diff --git a/packages/web/src/components/number-flow/tests/number-flow.test.ts b/packages/web/src/components/number-flow/tests/number-flow.test.ts
index 45defec9ff..862ec836e6 100644
--- a/packages/web/src/components/number-flow/tests/number-flow.test.ts
+++ b/packages/web/src/components/number-flow/tests/number-flow.test.ts
@@ -4,6 +4,7 @@ import userEvent from '@testing-library/user-event'
import { mount as Basic } from '../../../../examples/number-flow/basic.js'
import { mount as Formatting } from '../../../../examples/number-flow/formatting.js'
import { mount as PrefixSuffix } from '../../../../examples/number-flow/prefix-suffix.js'
+import { mount as WithTimer } from '../../../../examples/number-flow/with-timer.js'
import { mount } from '../../../test-utils.js'
const user = userEvent.setup()
@@ -48,3 +49,13 @@ test('number flow formats with formatOptions', async () => {
expect(texts()[1]).toBe('+12.4%')
expect(texts()[2]).toBe('1.3M')
})
+
+test('number flow follows a countdown timer and resets with it', async () => {
+ mount(WithTimer)
+ const [minutes, seconds] = document.querySelectorAll('ark-number-flow')
+ await waitFor(() => expect([minutes.value, seconds.value]).toEqual([5, 0]))
+ await user.click(screen.getByRole('button', { name: 'Start' }))
+ await waitFor(() => expect(minutes.value).toBe(4), { timeout: 3000 })
+ await user.click(screen.getByRole('button', { name: 'Reset' }))
+ await waitFor(() => expect([minutes.value, seconds.value]).toEqual([5, 0]))
+})
diff --git a/website/src/content/pages/utilities/number-flow.mdx b/website/src/content/pages/utilities/number-flow.mdx
index 29b92f4946..22cda64af3 100644
--- a/website/src/content/pages/utilities/number-flow.mdx
+++ b/website/src/content/pages/utilities/number-flow.mdx
@@ -103,6 +103,14 @@ when the number gains or loses a digit.
+### With Timer
+
+Pair `NumberFlow` with the [Timer](/docs/components/timer) to roll a countdown. Read the time from `useTimer`, render
+one `NumberFlow.Root` per unit with `minimumIntegerDigits: 2`, and set `trend={-1}` so every digit rolls down as the
+time runs out.
+
+
+
### Live Announcements
Set `live` to announce changes to screen readers. The value is announced through `HiddenValueText` once the roll