Svelte Countdown

ariefsn

A lightweight Svelte 5 timer component for counting down from a number or between two dates, with simple render via snippet and control methods

Download

Svelte Countdown

A lightweight Svelte 5 timer component for counting down from a number or between two dates, with simple render via snippet and control methods.

Install

# npm
npm install @ariefsn/svelte-countdown
# yarn
yarn add @ariefsn/svelte-countdown
# bun
bun add @ariefsn/svelte-countdown

Usage

Import the component from the package and render via the Svelte 5 children snippet. You can also bind the component instance to access start, stop, and reset.

Count down from a number

<script lang="ts">
  import { Countdown } from '@ariefsn/svelte-countdown';
</script>

<Countdown value={10} autoStart>
  {#snippet children(time, seconds)}
    {seconds}
  {/snippet}
</Countdown>

Count down between two dates

<script lang="ts">
  import { Countdown } from '@ariefsn/svelte-countdown';

  const from = new Date();
  const to = new Date(Date.now() + 15000);
</script>

<Countdown value={{ from, to }}>
  {#snippet children(time, seconds)}
    {time.minutes}:{time.seconds}
  {/snippet}
</Countdown>

Control methods and callbacks

<script lang="ts">
  import { Countdown, type CountdownInstance } from '@ariefsn/svelte-countdown';

  let timer: ReturnType<typeof Countdown> | null = null;

  const handleStart = () => console.log('started');
  const handleTick = (time, s: number) => console.log('tick', s, time);
  const handleFinish = () => console.log('finished');
</script>

<Countdown
  bind:this={timer}
  value={5}
  onStart={handleStart}
  onTick={handleTick}
  onFinish={handleFinish}
>
  {#snippet children(time, seconds)}
    {seconds}
  {/snippet}
</Countdown>

<button on:click={() => timer?.start()}>Start</button>
<button on:click={() => timer?.stop()}>Stop</button>
<button on:click={() => timer?.reset()}>Reset</button>

Props

Name	Type	Description	Required	Default
`value`	`number` or `{ from: Date; to: Date }`	Number of seconds to count down, or a date range.	Yes	—
`children`	`Snippet<[time: Omit<CountdownState, 'totalSeconds'>, seconds: number]>`	Snippet to render the live countdown state.	Yes	—
`autoStart`	`boolean`	Start automatically on mount.	No	`false`
`onTick`	`(time: Omit<CountdownState, 'totalSeconds'>, seconds: number) => void`	Called every second with derived time and remaining seconds.	No	—
`onStart`	`() => void`	Called when the countdown starts.	No	—
`onFinish`	`() => void`	Called when remaining seconds reach `0`.	No	—

Types

CountdownState returned to the children snippet and onTick:

{
  years: string;
  months: string;
  weeks: string;
  days: string;
  hours: string;
  minutes: string;
  seconds: string;
}

Local development

Start dev server: npm run dev
Run unit tests: npm run test
- Browser mode tests require Playwright browsers. If you see a browser error, install them with npx playwright install (or npx playwright install chromium).
Build package: npm run build

Everything inside src/lib is part of the library; src/routes is a simple showcase.

Top categories