Route Map · Youj

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 route map where the question is where a load, a courier or a crew is on its way, which stretch is late and what the alternative would be. There are no tiles: land, water, parks and roads are abstract shapes in the theme's tones, so the routes are the loudest thing on it and nothing loads from a map provider. For a world view of where traffic comes from, use a Dot Map; for the same stops as a line of steps, a Stepper with a detour.

import { RouteMap, type RouteMapRoute, type RouteMapStop } from '@youj/react'

const stops: RouteMapStop[] = [
  { id: 'depot', name: 'Harbor depot', kind: 'origin', x: 12, y: 72, detail: 'Departed 09:14' },
  { id: 'truck', name: 'Load 4821', kind: 'current', x: 43, y: 45, card: <p>+47 min</p> },
  { id: 'summit', name: 'Summit DC', kind: 'destination', x: 86, y: 18, detail: 'ETA 15:49' },
]
const routes: RouteMapRoute[] = [
  { id: 'driven', status: 'done', path: ['depot', [24, 60], 'truck'] },
  { id: 'ahead', status: 'delayed', path: ['truck', 'summit'] },
  { id: 'reroute', status: 'proposed', label: 'Proposed via river road', path: ['truck', [66, 57], 'summit'] },
]

<RouteMap stops={stops} routes={routes} />

Stops sit at x and y, from 0 to 100 across and down the map. Their kind picks the marker: origin, stop, destination, or current for where the vehicle is now (it pulses). Any stop takes your own icon: the current one wears it on the accent, the others on an ink disc, as a fleet map's other trucks do. A route's path lists what it passes through: stop ids, and [x, y] waypoints to bend it along the roads; the line is smoothed through them. Its status is done (driven, quiet), on-time (ink), delayed (the danger tone) or proposed (a dotted line in the accent), and its label names it in the legend.

A stop's card is anchored beside its marker and always shown: an ETA, a warning, a reroute to approve. It sits toward the middle of the map unless cardSide says left, right, top or bottom. Anything else you lay over the map (a summary card, zoom controls) goes in children. terrain swaps the built-in coast for your own shapes, as path data in a 100 × 100 box; ratio sets the map's width over its height (16 / 10).

Reference

Propsstops, routes, terrain… (9)

Props

RouteMap props
Prop	Type	Default
`stops`Required	`RouteMapStop[]`	–
`routes`Required	`RouteMapRoute[]`	–
`terrain`	`RouteMapTerrain` The land under the routes. default DEFAULT_TERRAIN	`DEFAULT_TERRAIN`
`value`	`string \| null` The picked stop's id (controlled); `null` for none.	–
`defaultValue`	`string \| null` The stop picked at first. default null	`null`
`onValueChange`	`(id: string \| null) => void`	–
`legend`	`boolean` Shows the legend of route states. default true	`true`
`ratio`	`number` The map's width over its height. default 16 / 10	`16 / 10`
`label`	`string` The map's accessible name. Default: the labels' "Route map".	–
`children`	`ReactNode` Your own overlays on the map: controls, a summary card.	–
Other props pass through: extends `ComponentProps<'div'>`.

Stops

RouteMapStop props
Prop	Type	Default
`id`Required	`string`	–
`name`Required	`string` "Harbor depot".	–
`x`Required	`number` Across the map, 0–100 from its left edge.	–
`y`Required	`number` Down the map, 0–100 from its top.	–
`kind`	`RouteMapStopKind` `'origin''stop''destination''current'` Its marker. default `stop`	`stop`
`detail`	`string` A line said with its name and shown on hover: "Departed 09:14", "ETA 15:49".	–
`icon`	`ReactNode` Your own marker face: a truck, a courier. The current position wears it on the accent; any other stop on an ink disc, in place of its dot.	–
`card`	`ReactNode` A card anchored beside the marker, always shown.	–
`cardSide`	`'left' \| 'right' \| 'top' \| 'bottom'` Which side of the marker the card sits on. Default: left or right, toward the middle of the map.	–

Routes

RouteMapRoute props
Prop	Type	Default
`id`Required	`string`	–
`path`Required	`(string \| RouteMapPoint)[]` What it passes through, in order: stop ids, and waypoints as [x, y] (0–100) to bend it along the roads.	–
`status`	`RouteMapStatus` `'done''on-time''delayed''proposed'` default `on-time`	`on-time`
`label`	`string` Its name in the legend and the text alternative: "AI proposed via ring road". Default: its state's word.	–

StylingParts and data attributes

MotionDraw-in, markers, cards, pulse · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Landfades in as the map scrolls into view	`duration.slowease.enter` 340ms · cubic-bezier(0.16, 1, 0.3, 1)	340mscubic-bezier(0.16, 1, 0.3, 1)
Routeseach draws along its length: driven, then on time, delayed and proposed, one state after another	`duration.deliberateease.emphasized` 560ms · cubic-bezier(0.6, 0, 0.1, 1)	560mscubic-bezier(0.6, 0, 0.1, 1)
Markersland as their first line starts; the destination settles	`spring.snappy` 0.2s, bounce 0	0.2s, bounce 0
Cardsrise in after their marker	`duration.baseease.enter` 220ms · cubic-bezier(0.16, 1, 0.3, 1)	220mscubic-bezier(0.16, 1, 0.3, 1)
Current positiona ring opens and fades, only while the map is on screen	`duration.deliberateease.exit` 560ms · cubic-bezier(0.4, 0, 1, 1)	560mscubic-bezier(0.4, 0, 1, 1)

Reduced motion

Everything is drawn in place, and the current position doesn't pulse.

Reduced motion

Routes, markers and cards are drawn in place and the current position holds still. The states read the same: color, dots and the legend carry them.

AccessibilityGroup, markers, text alternative