Track Timeline

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 track timeline for an edit made of parts on tracks: a podcast cut, a song sketch, a video's voice-over, a meeting's highlights. Each track is a lane in its chart color with its name, mute and solo keys and a level strip; each clip is a rounded bar holding the slice of the track's sound it plays, drawn from loudness samples you pass (it decodes no audio) and scaled by its gain. Drag a clip to move it, or its edges to trim it. Both snap to the other clips' edges and to the playhead, and a guide shows the edge they caught. A ruler of mono timecodes runs along the top, with the playhead on it. For a single recording's seek bar, use a Waveform Scrubber.

import { TrackTimeline } from '@youj/react'

<TrackTimeline
  tracks={[
    { id: 'host', name: 'Host', caption: 'Mic 1', peaks: hostPeaks },
    { id: 'music', name: 'Music bed', peaks: musicPeaks, muted: true },
  ]}
  clips={clips}
  onClipsChange={setClips}
  onTrackChange={(id, change) => updateTrack(id, change)}
  duration={30}
  position={time}
  onPositionChange={setTime}
  value={selected}
  onValueChange={setSelected}
/>

clips is controlled: every move and trim reports the whole list through onClipsChange. A clip sits from start to end on its track, plays its track's source from offset, and scales its wave by gain in decibels. A track's peaks are its whole source as loudness from 0 to 1, one sample every resolution seconds (0.1). A clip never moves into its neighbor on the same track, never trims past its source, and stays at least half a second long. formatClipTime(seconds, locale) formats times the way the timeline speaks them (0:12.5).

Reference

Propstracks, clips, duration… (21)

Props

TrackTimeline props
Prop	Type	Default
`tracks`Required	`readonly TimelineTrack[]`	–
`clips`Required	`readonly TimelineClip[]` The clips (controlled): every move and trim reports the whole list.	–
`onClipsChange`	`(clips: TimelineClip[]) => void`	–
`onTrackChange`	`(id: string, change: { muted?: boolean; solo?: boolean }) => void`	–
`duration`Required	`number` The timeline's length, in seconds.	–
`position`	`number` The playhead, in seconds (controlled).	–
`defaultPosition`	`number` default 0	`0`
`onPositionChange`	`(seconds: number) => void`	–
`value`	`string \| null` The selected clip's id (controlled); `null` for none.	–
`defaultValue`	`string \| null` default null	`null`
`onValueChange`	`(id: string \| null) => void`	–
`zoom`	`number` Pixels per second (controlled). Default: the whole timeline in view, at least 8.	–
`defaultZoom`	`number`	–
`onZoomChange`	`(pxPerSecond: number) => void`	–
`resolution`	`number` Seconds per sample in the tracks' peaks. default 0.1	`0.1`
`snap`	`boolean` Snap moves and trims to the other clips' edges and the playhead. default true	`true`
`step`	`number` Seconds an arrow key moves or trims a clip. default 0.5	`0.5`
`playing`	`boolean` While playing, the meters read the tracks at the playhead and the lane follows it. default false	`false`
`label`	`string` The timeline's accessible name. Default: the labels' "Timeline".	–
`locale`	`string` Default: the YoujProvider locale.	–
`sound`	`boolean` With sound on, catching a snap point plays `tick`. default true	`true`
Other props pass through: extends `ComponentProps<'div'>`.

StylingParts and data attributes

MotionPlaying, drag and trim, handles · reduced motion

Motion

Motion tokens
Moment	Tokens	Value
Playingeach level strip eases between readings as the playhead passes through the track’s clips	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)
Drag and trimthe clip and its edges follow the pointer, never eased; a snap shows its guide at once	no token
Handlesa trim handle thickens on hover	`duration.fastease.standard` 140ms · cubic-bezier(0.2, 0, 0, 1)	140mscubic-bezier(0.2, 0, 0, 1)

Reduced motion

The level strips jump to each reading; everything else was never eased.

Reduced motion

The level strips jump to each reading instead of easing. Dragging, trimming and the playhead are unchanged, since they never animate.

AccessibilityKeyboard, ARIA, focus