svelte-film-countdown

A vintage-style film countdown component for your Svelte 5 applications, built with runes.

Features

• Authentic Vintage Aesthetic: Provides a visually compelling retro film countdown experience reminiscent of classic cinema.
• Highly Customizable: Tailor the countdown's behavior and appearance with props and CSS variables. Control duration, initial count, styling of circles, numbers, and visual effects.
• Programmatic Control: Imperatively manage the countdown's state using exported functions: start, pause, resume, and reset.
• Event Callbacks: Execute custom logic when the countdown completes (onComplete) or after each decrement (onEachCount).
• Looping Functionality: Enable continuous countdown loops with the loop prop.
• CSS Variable Theming: Achieve consistent branding and easily adjust the visual theme using CSS variables.

Installation

Install svelte-film-countdown using your preferred package manager:

npm install svelte-film-countdown

yarn add svelte-film-countdown

pnpm add svelte-film-countdown

bun add svelte-film-countdown

Usage

Import the FilmCountdown component into your Svelte component:

<script>
  import FilmCountdown from 'svelte-film-countdown';

  let countdownInstance;

  function handleComplete() {
    alert('Countdown finished!');
  }

  function handleEachCount(currentCount) {
    console.log('Current count:', currentCount);
  }

  function startCountdown() {
    countdownInstance?.start();
  }

  function pauseCountdown() {
    countdownInstance?.pause();
  }

  function resumeCountdown() {
    countdownInstance?.resume();
  }

  function resetCountdown() {
    countdownInstance?.reset();
  }
</script>

<FilmCountdown
  bind:this={countdownInstance}
  initialCount={5}
  countdownDuration={1000}
  onComplete={handleComplete}
  onEachCount={handleEachCount}
/>

<br />
<button on:click={startCountdown}>Start</button>
<button on:click={pauseCountdown}>Pause</button>
<button on:click={resumeCountdown}>Resume</button>
<button on:click={resetCountdown}>Reset</button>

Basic Example

Render the countdown with default settings:

<script>
  import FilmCountdown from 'svelte-film-countdown';
</script>

<FilmCountdown />

Custom Initial Count and Duration

Configure the starting number and the duration of each count:

<script>
  import FilmCountdown from 'svelte-film-countdown';
</script>

<FilmCountdown initialCount={10} countdownDuration={500} />

Utilizing Event Callbacks

Execute functions when the countdown finishes or after each count:

<script>
  import FilmCountdown from 'svelte-film-countdown';

  function handleComplete() {
    console.log('Countdown finished!');
  }

  function handleEachCount(currentCount) {
    console.log('Current count:', currentCount);
  }
</script>

<FilmCountdown onComplete={handleComplete} onEachCount={handleEachCount} />

Configuration Options via config Prop

Customize the visual appearance of the countdown through the config prop:

<script>
  import FilmCountdown from 'svelte-film-countdown';
</script>

<FilmCountdown
  initialCount={3}
  config={{
    numberColor: "red",
    numCircles: 4
  }}
/>

Enabling Looping

Make the countdown restart automatically after reaching zero. Note that you need to manually trigger start() to begin the countdown:

<script>
  import FilmCountdown from 'svelte-film-countdown';
  let countdownInstance;

  function startLoopingCountdown() {
    countdownInstance?.start();
  }
</script>

<FilmCountdown bind:this={countdownInstance} loop={true} />
<button on:click={startLoopingCountdown}>Start Looping Countdown</button>

Props

config Object Properties

Exported Functions

To control the countdown programmatically, you need to bind a reference to the FilmCountdown component using bind:this.

• start(): Initiates the countdown sequence.
• pause(): Temporarily halts the countdown.
• resume(): Continues the countdown from the paused state.
• reset(): Stops the countdown and resets it to the initialCount.

Theming with CSS Variables

Customize the visual theme of the FilmCountdown component by overriding these CSS variables in your global stylesheet or within a specific component's <style> block.

:root {
  --countdown-number-color: black;
  --countdown-button-color: rgba(0, 0, 0, 0.8);
  --countdown-button-text-color: white;

  --film-hole-width: 20px;
  --film-hole-rect-width: 8px;
  --film-hole-rect-height: 12px;
  --film-hole-y-top: 10px;
  --film-hole-y-bottom: 22px;
  --film-hole-color: black;

  --sweeping-background-color: rgba(0, 0, 0, 0.15);

  --circle-gradient-start: black;
  --circle-gradient-middle: black;
  --circle-gradient-middle-opacity: 0.8;
  --circle-gradient-end: black;

  --grid-line-color: rgba(255, 255, 255, 0.3);
  --film-grain-opacity: 0.1;
  --flicker-duration: 0.15s;
  --vignette-strength: 0.4;
  --center-vignette-strength: 0.15;
  --scratch-color: rgba(255, 255, 255, 0.2);
  --scratch-opacity: 0.15;
  --number-font: monospace;
  --number-text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5);
  --film-grain-pattern: linear-gradient(to bottom, rgba(156, 163, 175, 0.05), transparent, rgba(156, 163, 175, 0.05));
}

Example of Applying a Theme:

<style>
  :root {
    --countdown-number-color: lightyellow;
    --sweeping-background-color: rgba(100, 0, 0, 0.25);
    --film-grain-opacity: 0.2;
  }
</style>

<FilmCountdown />

Contributing

Contributions are highly appreciated! If you find a bug, have an idea for an improvement, or want to add a new feature, please don't hesitate to open an issue or submit a pull request.

License

MIT License