react-stopwatch-pro

React stopwatch component with laps, merge/delete, manual time override, swipe hints on small screens, and a headless useStopwatch hook. Written in TypeScript.

Live demo (GitHub Pages): after you enable Pages (see below), your site will be at
https://<your-username>.github.io/<repository-name>/
For a repo named react-stopwatch-pro under user myuser, that is
https://myuser.github.io/react-stopwatch-pro/.

Features

• Start / stop / lap / reset with lap list and current split display
• Optional manual time override (MM:SS:CS)
• Delete or merge laps (with confirmation modals); swipe hints on narrow viewports
• Callbacks: onStart, onStop(time), onReset, onLap(lapMs, totalMs)
• showLaps and className props
• formatStopwatchTime helper (MM:SS:CS)

Install

npm install react-stopwatch-pro

Peer dependencies: react and react-dom 18+.

Styling

The built-in UI uses Tailwind CSS utility classes. Your app must include Tailwind with content globs that cover this library’s source (or your bundled output), for example:

// tailwind.config.js
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/react-stopwatch-pro/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      keyframes: {
        "scale-in": {
          "0%": { opacity: "0", transform: "scale(0.96)" },
          "100%": { opacity: "1", transform: "scale(1)" },
        },
      },
      animation: {
        "scale-in": "scale-in 0.2s ease-out forwards",
      },
    },
  },
};

Modal panels use the animate-scale-in animation; add the keyframes above if you do not already have them.

Usage

<Stopwatch />

import { Stopwatch } from "react-stopwatch-pro";

export function App() {
  return (
    <Stopwatch
      className="max-w-md mx-auto"
      showLaps
      onStart={() => console.log("started")}
      onStop={(elapsedMs) => console.log("stopped at", elapsedMs)}
      onReset={() => console.log("reset")}
      onLap={(lapMs, totalMs) => console.log("lap", lapMs, "total", totalMs)}
    />
  );
}

Props

Prop	Type	Default	Description
autoStart	boolean	false	Start the timer on mount
showLaps	boolean	true	Render lap list UI
className	string	""	Extra classes on the root element
onStart	() => void	—	Fires when starting
onStop	(timeMs: number) => void	—	Fires when stopping; timeMs is elapsed
onReset	() => void	—	Fires when reset
onLap	(lapMs: number, totalMs: number) => void	—	Fires when a lap is recorded

useStopwatch hook

Use the same timing/lap logic with your own UI:

import { useStopwatch, formatStopwatchTime } from "react-stopwatch-pro";

export function CustomUI() {
  const sw = useStopwatch({});

  return (
    <div>
      <output>{formatStopwatchTime(sw.time)}</output>
      {/* use sw.handleStart, sw.handleStop, sw.handleLap, sw.laps, … */}
    </div>
  );
}

Repository layout

Path	Role
src/stopwatch/Stopwatch.tsx	Composes UI
src/stopwatch/useStopwatch.ts	Timer state and lap logic
src/stopwatch/formatStopwatchTime.ts	Time formatter
src/stopwatch/StopwatchDisplay.tsx	Display + override panel
src/stopwatch/StopwatchControls.tsx	Control buttons
src/stopwatch/StopwatchLapList.tsx	Lap list + swipe
src/stopwatch/DeleteLapModal.tsx / MergeLapModal.tsx	Confirm dialogs
demo/	Vite + React demo site (GitHub Pages)

Demo site & GitHub Pages

The demo/ app is a small Vite + React + Tailwind site that imports the library from ../src via a Vite alias (no publish needed for the demo build).

Run locally

From the repo root:

npm run demo:dev

Then open the URL Vite prints (usually http://localhost:5173).

To produce a production build of the library and the demo:

npm run demo:build
npm run demo:preview   # optional local check of demo/dist

Deploy with GitHub Actions

1. Push this repo to GitHub (default branch main or master — both are wired in the workflow).
2. Open Settings → Pages.
3. Under Build and deployment, set Source to GitHub Actions (not “Deploy from a branch”).
4. The workflow Deploy demo to GitHub Pages (.github/workflows/deploy-pages.yml) builds the library, builds demo/ with the correct asset base path (/<repository-name>/), and publishes demo/dist to Pages.
5. After the first successful run, Pages shows your demo URL (typically https://<user>.github.io/<repo>/).

The demo’s “View on GitHub” link is set at build time via VITE_REPO_URL in the workflow. For local dev you can add a demo/.env file:

VITE_REPO_URL=https://github.com/you/react-stopwatch-pro

Library development

npm install
npm run build      # tsup → dist/
npm run typecheck
npm run test       # Vitest + Testing Library
npm run test:watch
npm run dev        # tsup --watch

License

MIT