Lifeline: A Shadcn Registry Timeline Component for Careers, Companies, and Journeys

A Timeline That Lives in Your Codebase, Not a Dependency

Lifeline ships as a shadcn registry item, which means the install command copies source code directly into your project rather than adding a versioned npm package. The components land in components/lifeline/, the data helper lands in lib/lifeline-data.ts, and intro keyframes are added to your CSS. You own the code from that point: every easing curve, breakpoint, and class is editable.

The trade-off compared to a traditional npm package is that updates to the upstream Lifeline repository require a manual re-run of the install command or a manual diff. There is no package version to bump. Teams that want automatic dependency updates through tools like Renovate or Dependabot will not get them.

The target users are developers building pages where a timeline is the primary content: a career history, a company founding story, or an event sequence. The component is designed to be the page rather than a widget sitting inside one, though embedded mode makes in-page use possible.

Horizontal Scroll-Scrub on Desktop, Vertical on Mobile

The layout switches automatically at the md Tailwind breakpoint. Above md, the timeline renders horizontally, with the years distributed along a single rail that advances as the user scrolls the page. The scroll position scrubs the rail, so the page does not scroll down while the timeline still has rail left to travel. Below md, the layout becomes a vertical scrolling list.

The mode prop controls whether the timeline owns the page scroll or borrows it. The default auto mode measures the container. The page mode assumes the timeline owns the full viewport. The embed mode, intended for timelines placed inside a page with other content, borrows the scroll wheel only while the rail has distance to cover, then returns control to the page scroll. The README includes this note about embed mode: a gesture already in flight passes through without being captured, so a fast flick on the page does not accidentally advance the rail.

The LifelineNav component is specifically the reason the rail sits inset rather than bleeding to the full screen width. Its left edge anchors the start of the rail.

Installing Lifeline with npx shadcn

To install a complete page with routing:

npx shadcn@latest add evilrabbit/lifeline/page

This installs components, starter data, the shell, and a route at app/lifeline/page.tsx. If that route already exists, shadcn asks before overwriting.

To take only the shell without creating a route:

npx shadcn@latest add evilrabbit/lifeline/shell

For a data template matched to a specific subject, three starters are available:

npx shadcn@latest add evilrabbit/lifeline/personal
npx shadcn@latest add evilrabbit/lifeline/company
npx shadcn@latest add evilrabbit/lifeline/journey

To get just the component system without any framing:

npx shadcn@latest add evilrabbit/lifeline/lifeline

Any of these installs lucide-react and next-themes as dependencies. The registry is also served at https://evilrabbit.com/r/{name}.json for direct URL installs.

Defining Milestones and What They Can Carry

Data is defined using the defineLifeline function from lib/lifeline-data.ts. The function accepts a configuration object with slug, name, birthYear, an optional endYear, a description, and a milestones record keyed by year.

Each year's entry can carry several types of content. The events field accepts plain strings or objects with text, an optional image URL that appears on hover on desktop and on tap on mobile, and an optional video URL that makes the hover image loop. The effect field supports a fireworks easter egg triggered by clicking the event.

The photos field attaches media cards directly to the timeline rail. These are positioned with x and y coordinates (each 0 to 1, across the year's slot), an optional rotation, and an optional width. They can be dragged on desktop and tap-expanded on mobile.

The companies field registers organization marks against the rail using icons registered via registerCompanyIcons. The mentors and met fields add person rows with portraits. The age field overrides the computed age label for a year, which is useful for tournament-style chronologies where a label like QF makes more sense than a number.

Embedding the Timeline Inside a Page

A full-page timeline that owns the scroll wheel is Lifeline's primary use case, but the component supports embedding within a page that has other content. Passing mode='embed' and a height is the documented approach:

The README describes two details specific to embed mode. First, when the rail runs out, the scroll wheel goes back to the page, so the visitor's page continues scrolling naturally. Second, a gesture already in motion is never captured by the timeline: a fast flick on the page passes through the embedded timeline without advancing the rail. Only a deliberate scroll over the timeline scrubs it.

The container width cap is shared between LifelineNav and LifelineFooter through the containerClassName prop. If those two props are not kept in sync, the rail's end point will not align with the footer's edge, which the README specifically calls out as a visual inconsistency to watch for.

What Lifeline Does Not Handle

The component is built for Next.js with the app router. The shell and route generation in the page install assume Next.js conventions. Using Lifeline in a plain React application without Next.js, or with the pages router, requires adapting the installed files manually: the route file, the layout conventions, and the theme-switcher setup all tie into Next.js specifics.

The last push to the repository was on 2026-07-31. There are no GitHub releases, and the package version in package.json is 0.1.0. The project is at an early version, and the installed component code may diverge from the upstream repository without an automated mechanism to detect or apply updates.

The component ships with lucide-react and next-themes as required dependencies. Projects that use a different icon set or a different theming system will need to substitute those dependencies after installation.

MIT License and the shadcn Registry Model

Lifeline is released under the MIT license, permitting commercial use, modification, and redistribution without restrictions. The shadcn registry delivery model means the license applies to the source files copied into your project; there is no ongoing dependency link to the upstream repository after installation.

The project depends on Next.js 16.2.10, React 19.2.4, Tailwind CSS 4, and shadcn 4.13.1 per the package.json. The workspace uses pnpm. Because the installed files reference these dependency versions through your project's own package.json after shadcn adds them, the versions in the Lifeline source repository are the target but your project's lock file controls what is actually installed. If you need the original source to apply a manual update, the upstream registry JSON is available at https://evilrabbit.com/r/lifeline.json.

Editorial conclusion

Lifeline is a good fit for developers who want a polished, configurable timeline without writing the layout from scratch, and who are already using Next.js and Tailwind CSS. It is not a good fit for React applications that do not use Next.js, because the shell and routing assume the Next.js app router. Before installing, confirm that your project uses pnpm and Next.js 16 or later: the package.json shows next at 16.2.10 and the workspace uses pnpm, and deviating from that stack may require adjusting the install output by hand.

Frequently asked questions

Official sources

1. evilrabbit/lifeline on GitHub
2. Issues
3. License: MIT
4. Project website
5. README