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.

• GitHub: https://github.com/ariefsn/svelte-countdown
• NPM: http://npmjs.com/package/@ariefsn/svelte-countdown

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.