⬅️ Back to Table of Contents

📄 useCountdown

📊 Analysis Summary

Metric	Count
🔧 Functions	5
📦 Imports	8
📐 Interfaces	2

📚 Table of Contents

• Imports
• Functions
• Interfaces

🛠️ File Location:

📂 packages/core/useCountdown/index.ts

📦 Imports

Name	Source
AnyFn	@vueuse/shared
Pausable	@vueuse/shared
MaybeRefOrGetter	vue
ShallowRef	vue
ConfigurableScheduler	../_configurable
useIntervalFn	@vueuse/shared
shallowRef	vue
toValue	vue

---

Functions

useCountdown(initialCountdown: MaybeRefOrGetter<number>, options: UseCountdownOptions): UseCountdownReturn

Reactive countdown timer in seconds.

Parameters:

• initialCountdown any: No description
• options any: No description

See: https://vueuse.org/useCountdown

Raw JSDoc

/**
 * Reactive countdown timer in seconds.
 *
 * @param initialCountdown
 * @param options
 *
 * @see https://vueuse.org/useCountdown
 */

Calls:

• shallowRef (from vue)
• toValue (from vue)
• useIntervalFn (from @vueuse/shared)
• scheduler
• onTick
• controls.pause
• onComplete
• reset
• controls.resume

Code

export function useCountdown(initialCountdown: MaybeRefOrGetter<number>, options: UseCountdownOptions = {}): UseCountdownReturn {
  const remaining = shallowRef(toValue(initialCountdown))

  const {
    scheduler = (cb: AnyFn) => useIntervalFn(cb, 1000, { immediate: false }),
    onTick,
    onComplete,
  } = options

  const controls = scheduler(() => {
    const value = remaining.value - 1
    remaining.value = value < 0 ? 0 : value
    onTick?.()
    if (remaining.value <= 0) {
      controls.pause()
      onComplete?.()
    }
  })

  const reset = (countdown?: MaybeRefOrGetter<number>) => {
    remaining.value = toValue(countdown) ?? toValue(initialCountdown)
  }

  const stop = () => {
    controls.pause()
    reset()
  }

  const resume = () => {
    if (!controls.isActive.value) {
      if (remaining.value > 0) {
        controls.resume()
      }
    }
  }

  const start = (countdown?: MaybeRefOrGetter<number>) => {
    reset(countdown)
    controls.resume()
  }

  return {
    remaining,
    reset,
    stop,
    start,
    pause: controls.pause,
    resume,
    isActive: controls.isActive,
  }
}

Internal helpers

Declared inside another function in this file.

reset(countdown: MaybeRefOrGetter<number>): void

Parameters:

• countdown MaybeRefOrGetter<number>

Returns: void

Calls:

• toValue (from vue)

Code

(countdown?: MaybeRefOrGetter<number>) => {
    remaining.value = toValue(countdown) ?? toValue(initialCountdown)
  }

stop(): void

Returns: void

Calls:

• controls.pause
• reset

Code

() => {
    controls.pause()
    reset()
  }

resume(): void

Returns: void

Calls:

• controls.resume

Code

() => {
    if (!controls.isActive.value) {
      if (remaining.value > 0) {
        controls.resume()
      }
    }
  }

start(countdown: MaybeRefOrGetter<number>): void

Parameters:

• countdown MaybeRefOrGetter<number>

Returns: void

Calls:

• reset
• controls.resume

Code

(countdown?: MaybeRefOrGetter<number>) => {
    reset(countdown)
    controls.resume()
  }

---

Interfaces

UseCountdownOptions

Interface Code

export interface UseCountdownOptions extends ConfigurableScheduler {
  /**
   * Callback function called when the countdown reaches 0.
   */
  onComplete?: () => void
  /**
   * Callback function called on each tick of the countdown.
   */
  onTick?: () => void
}

Properties

Name	Type	Optional	Description
onComplete	() => void	✓	not shown
onTick	() => void	✓	not shown

UseCountdownReturn

Interface Code

export interface UseCountdownReturn extends Pausable {
  /**
   * Current countdown value.
   */
  remaining: ShallowRef<number>
  /**
   * Resets the countdown and repeatsLeft to their initial values.
   */
  reset: (countdown?: MaybeRefOrGetter<number>) => void
  /**
   * Stops the countdown and resets its state.
   */
  stop: () => void
  /**
   * Reset the countdown and start it again.
   */
  start: (countdown?: MaybeRefOrGetter<number>) => void
}

Properties

Name	Type	Optional	Description
remaining	ShallowRef<number>	✗	not shown
reset	(countdown?: MaybeRefOrGetter<number>) => void	✗	not shown
stop	() => void	✗	not shown
start	(countdown?: MaybeRefOrGetter<number>) => void	✗	not shown

---

Generated by Syntax Scribe