A sleek, minimalist date distance calculator. Pick any date and instantly see how much time has passed — or remains — broken down into years, months, days, weeks, and hours. Plus contextual fun facts like heartbeats elapsed and Mars orbits completed.
- Bidirectional — works for past dates ("ago") and future dates ("from now")
- Custom reference date — compare any two dates, not just against today
- Multiple units — years/months/days breakdown plus total days, weeks, and hours
- Fun facts — contextual stats (heartbeats, Moon cycles, Mars orbits, and more)
- Shareable URLs — every calculation is encoded in the URL (
?date=2023-05-14&from=2025-01-01) - Copy to clipboard — one-click copy of the result text or share link
- Keyboard shortcut —
Cmd/Ctrl + Kto focus the date picker - Dark / Light theme — dark by default with a toggle, preference saved in cookies
- Remembers your last date — persisted via cookies across sessions
- Responsive — fully mobile-friendly with a sticky header on small screens
- PWA-ready — includes a web app manifest for installability
- Accessible — semantic HTML,
ariaattributes,focus-visiblestates, andprefers-reduced-motionsupport
| Layer | Technology |
|---|---|
| Framework | React 19 with React Compiler |
| Language | TypeScript 5.9 (strict mode) |
| Build | Vite 7 |
| Styling | Tailwind CSS v4 |
| Dates | date-fns 4 |
| Animation | Framer Motion 12 |
| Cookies | js-cookie |
| Linting | ESLint with TypeScript + React Hooks plugins |
- Node.js 18+
- npm (ships with Node)
git clone https://github.com/t21dev/how-long.git
cd how-long
npm installnpm run devOpens a local dev server at http://localhost:5173 with hot module replacement.
npm run buildType-checks with tsc then bundles with Vite. Output goes to dist/.
npm run previewnpm run lintnpm run generate:ogConverts public/og-image.svg to public/og-image.png (1200x630) using sharp.
src/
├── components/
│ ├── DateInput.tsx # Native date picker with accessible label support
│ ├── ResultDisplay.tsx # Primary + secondary time distance output
│ ├── FunFact.tsx # Contextual fun stat with animated transitions
│ ├── ThemeToggle.tsx # Dark/light mode toggle button
│ └── FromDateToggle.tsx # Today / Custom reference date selector
├── hooks/
│ └── useDateDistance.ts # Core date calculation logic (date-fns)
├── utils/
│ ├── cookies.ts # Cookie get/set/remove wrapper (js-cookie)
│ └── funFacts.ts # Deterministic fun fact generator
├── App.tsx # Root component — state, effects, layout
├── main.tsx # Entry point — React root + MotionConfig
└── index.css # Tailwind v4 import + dark mode variant + base styles
| Param | Example | Description |
|---|---|---|
date | ?date=2023-05-14 | Target date to calculate distance for |
from | &from=2025-01-01 | Optional custom reference date (defaults to today) |
Both parameters are synced to the URL as you interact, making every result shareable by copying the address bar.
| Shortcut | Action |
|---|---|
Cmd/Ctrl + K | Focus the date picker |
The app stores two cookies (expire after 1 year, SameSite=Lax):
| Cookie | Purpose |
|---|---|
howlong-target-date | Remembers the last date you entered |
howlong-theme | Persists your dark/light theme preference |
No analytics, no tracking, no third-party cookies.
The project works out of the box on any static hosting platform:
- Vercel —
npm run build, output dirdist - Netlify — same as above
- Cloudflare Pages — same as above
- GitHub Pages — build and deploy
dist/
Note: For Open Graph images to work on social platforms, update the
og:imagemeta tag inindex.htmlto use your full production URL (e.g.,https://yourdomain.com/og-image.png).
Contributions are welcome. To get started:
- Fork the repository
- Create a feature branch (
git checkout -b feat/my-feature) - Make your changes
- Run
npm run lintandnpm run buildto verify - Commit and push
- Open a Pull Request
This project is open source and available under the MIT License.
Built by t21dev