🌬 BreathKit

A zero-dependency TypeScript library for guided breathing exercises — box breathing, 4-7-8, cardiac coherence, and custom patterns.

Live Demo →

Features

• Zero dependencies — pure TypeScript, works anywhere
• Built-in patterns — Cardiac Coherence, 4-7-8, Box Breathing
• Fully customizable — define any pattern with any phases and durations
• Event-driven API — onPhaseChange, onTick, onCycleComplete, onComplete
• Simple state machine — start, pause, resume, stop

Installation

npm install breathkit

Quick Start

import { BreathKit, Patterns } from 'breathkit';

const kit = new BreathKit({
  pattern: Patterns.boxBreathing,
  cycles: 5,
  onPhaseChange: (phase) => {
    console.log(`→ ${phase.label} for ${phase.duration}s`);
  },
  onTick: (secondsRemaining) => {
    console.log(`  ${secondsRemaining}s remaining`);
  },
  onComplete: () => {
    console.log('Session complete!');
  },
});

kit.start();

Built-in Patterns

| Pattern | Phases | Best for | |---|---|---| | Patterns.coherenceCardiaque | 5s inhale / 5s exhale | Emotional regulation | | Patterns.fourSevenEight | 4s inhale / 7s hold / 8s exhale | Stress & sleep | | Patterns.boxBreathing | 4-4-4-4 | Focus & calm |

Custom Patterns

import { BreathKit, createPattern } from 'breathkit';

const myPattern = createPattern({
  id: 'my-pattern',
  name: 'My Pattern',
  description: 'A custom breathing pattern',
  phases: [
    { name: 'inhale', label: 'Breathe in',  duration: 4 },
    { name: 'hold',   label: 'Hold',        duration: 4 },
    { name: 'exhale', label: 'Breathe out', duration: 6 },
  ],
});

const kit = new BreathKit({ pattern: myPattern });
kit.start();

API

new BreathKit(options)

| Option | Type | Default | Description | |---|---|---|---| | pattern | Pattern | required | The breathing pattern to follow | | cycles | number | 0 | Number of cycles (0 = infinite) | | onPhaseChange | function | — | Called when a phase starts | | onTick | function | — | Called every second | | onCycleComplete | function | — | Called at the end of each cycle | | onComplete | function | — | Called when all cycles are done |

Methods

kit.start()   // Start the session
kit.pause()   // Pause (preserves state)
kit.resume()  // Resume after pause
kit.stop()    // Stop and reset

Getters

kit.state              // 'idle' | 'running' | 'paused' | 'completed'
kit.currentPhase       // Current Phase object
kit.currentPhaseIndex  // Index within the pattern
kit.currentCycle       // Current cycle number (1-based)
kit.secondsRemaining   // Seconds left in current phase

Use in a browser (no bundler)

The demo/ folder shows a complete vanilla JS implementation you can use as a starting point. Just copy the class from demo/index.html — no build step needed.

License

MIT