feat(useNow): expose immediate option (#4768)

scottbedard · web-flow · commit 4466058d1741 · 2025-05-23T17:09:58.000Z
diff --git a/packages/core/useNow/index.test.ts b/packages/core/useNow/index.test.ts
@@ -9,6 +9,19 @@ describe('useNow', () => {
     expect(+now.value).toBeLessThanOrEqual(+new Date())
   })
 
+  it('starts lazily if immediate is false', () => {
+    const initial = +new Date()
+    const { now, resume } = useNow({ controls: true, immediate: false })
+
+    expect(+now.value).toBe(initial)
+    vi.advanceTimersByTime(50)
+    expect(+now.value).toBe(initial)
+
+    resume()
+    vi.advanceTimersByTime(50)
+    expect(+now.value).toBeGreaterThan(initial)
+  })
+
   function testControl(interval: any) {
     it(`should control now timestamp by ${interval}`, async () => {
       let initial = +new Date()
diff --git a/packages/core/useNow/index.ts b/packages/core/useNow/index.ts
@@ -12,6 +12,13 @@ export interface UseNowOptions<Controls extends boolean> {
    */
   controls?: Controls
 
+  /**
+   * Start the clock immediately
+   *
+   * @default true
+   */
+  immediate?: boolean
+
   /**
    * Update interval in milliseconds, or use requestAnimationFrame
    *
@@ -32,15 +39,16 @@ export function useNow(options: UseNowOptions<boolean> = {}) {
   const {
     controls: exposeControls = false,
     interval = 'requestAnimationFrame',
+    immediate = true,
   } = options
 
   const now = deepRef(new Date())
 
   const update = () => now.value = new Date()
 
   const controls: Pausable = interval === 'requestAnimationFrame'
-    ? useRafFn(update, { immediate: true })
-    : useIntervalFn(update, interval, { immediate: true })
+    ? useRafFn(update, { immediate })
+    : useIntervalFn(update, interval, { immediate })
 
   if (exposeControls) {
     return {
