Milestone Ruler

Installation & usage

npm i @youj/react

For an app already set up with npx @youj/cli init, which installs the peers (@youj/core, @youj/motion, motion and Base UI) and wires the provider. New app? Start at Installation.

Use a milestone ruler for when things land across a long span: a product's year of releases, a quarter's launch plan, a grant's reporting dates. It answers "what's next, what slipped, how far along are we" at a glance and keeps one line of detail a hover away. For the order of steps in one flow use a Stage Rail; for events and durations within one incident, a Severity Timeline. The Roadmap timeline card is built on it.

import { MilestoneRuler, type Milestone } from '@youj/react'

const milestones: Milestone[] = [
  { id: 'v1-5', date: '2026-06-04', title: 'Version 1.5', description: 'New editor', major: true },
  { id: 'sso', date: '2026-10-28', title: 'SSO and audit log', status: 'at-risk' },
  { id: 'v2', date: '2026-11-26', title: 'Version 2', description: 'Rebuilt sync engine', major: true },
]

<MilestoneRuler milestones={milestones} today={today} label="Roadmap 2026" />

A milestone's date is a day: a date-only string such as "2026-11-26" is that calendar day in every time zone, and a Date or a time in ms counts by its local date. Without start and end the ruler spans January 1 to December 31 of today's year. status is done, upcoming or at-risk; left out, it is done before today and upcoming from it on. Pass today from your server so the page hydrates with the same marks; without it the ruler waits for the browser's clock. major draws a taller pin.

Milestones closer than about ten pixels share one pin with their count, so the grouping follows the space the ruler has. A picked milestone (value, or the next one from today by default) keeps its callout shown; hovering or focusing another shows that one until the pointer or focus leaves. formatDate writes the days your way.

Reference

Propsmilestones, start, end, today, value, tone…

Props

MilestoneRuler props
Prop	Type	Default
`milestones`Required	`readonly Milestone[]`	–
`start`	`MilestoneDate` The ruler's first day. Default: January 1 of today's year (or of the first milestone's).	–
`end`	`MilestoneDate` The ruler's last day. Default: December 31 of the start's year.	–
`today`	`MilestoneDate` Marked on the ruler, and splits done from upcoming. Default: the browser's clock once mounted (none on the server).	–
`value`	`string \| null` The selected milestone's id, shown when nothing is hovered or focused (controlled); `null` for none.	–
`defaultValue`	`string \| null` Default: the next milestone from today, else the last one.	–
`onValueChange`	`(id: string \| null) => void`	–
`tone`	`MilestoneRulerTone` `'accent''neutral''success''warning''danger''chart-1''chart-2''chart-3''chart-4''chart-5'` The pins' color. At-risk milestones take the warning tone. default 'accent'	`'accent'`
`formatDate`	`(date: Date) => string` Formats a day in the callout and the spoken names. Default: the locale's short month and day.	–
`locale`	`string` Default: the YoujProvider locale.	–
`label`	`string` Accessible name. Default: the labels' "Milestones".	–
Other props pass through: extends `ComponentProps<'div'>`.

StylingParts and data attributes

MotionRise, callout, stretch · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Risethe pins grow up from the ruler left to right when a third of it scrolls into view	`duration.deliberateease.enter` 560ms · cubic-bezier(0.16, 1, 0.3, 1)	560mscubic-bezier(0.16, 1, 0.3, 1)
Calloutthe callout glides to the pin under the pointer or focus, its caret staying on the pin	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)
Stretchthe ticks within about 40px of the pointer stretch toward it, most at the pointer	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)

Reduced motion

Drawn in place: the pins stand, the callout jumps and the ticks don't stretch.

Reduced motion

The pins are drawn standing, the callout moves at once and the ticks keep their length.

AccessibilityKeyboard, focus, screen readers