Canvas Timeline
Function

useTimelineViewportRangeControl

Adds formatted accessibility values to the timeline viewport range adapter. This hook builds on `useTimelineViewportScrollbar`, preserving the same lean viewport scrollbar geometry and keyboard behavior while adding `aria-valuetext` formatting for the thumb and resize handles. Use it with the generic `RangeScrollbar` primitive when composing a custom viewport control.

Signature

Type Definition
useTimelineViewportRangeControl(options: TimelineViewportRangeControlOptions = {}): object

Parameters

NameTypeDescription
optionsTimelineViewportRangeControlOptionsViewport scrollbar options plus optional decimal precision for spoken time values.

Returns

object

Timeline viewport metrics and `RangeScrollbar.Root` props with formatted value text.

Return members

NameSignatureDescription
endValueTextendValueText: stringFormatted visible viewport end time.
onValueChange(value: RangeScrollbarValue, details: RangeScrollbarValueChangeDetails): voidHandles controlled range changes by panning or zooming the timeline engine.
rangerange: UseRangeScrollbarResultGeneric range scrollbar state derived from timeline viewport state.
rootPropsrootProps: objectProps for `RangeScrollbar.Root`, including formatted `aria-valuetext`.
scrollLeftscrollLeft: numberCurrent horizontal timeline scroll offset in pixels.
startValueTextstartValueText: stringFormatted visible viewport start time.
totalDurationSecondstotalDurationSeconds: numberFull timeline duration represented by the scrollbar domain, in seconds.
valueTextvalueText: stringFormatted visible viewport range for assistive technology.
viewDurationSecondsviewDurationSeconds: numberVisible viewport duration in seconds.
viewEndSecondsviewEndSeconds: numberVisible viewport end time in seconds.
viewportWidthviewportWidth: numberMeasured timeline viewport width in pixels.
viewStartSecondsviewStartSeconds: numberVisible viewport start time in seconds.
zoomScalezoomScale: numberCurrent timeline zoom scale in pixels per second.

Examples

tsx Example
const viewport = useTimelineViewportRangeControl();


return (
  <RangeScrollbar.Root {...viewport.rootProps}>
    <RangeScrollbar.Thumb>
      <RangeScrollbar.Handle side="start" />
      <RangeScrollbar.Handle side="end" />
    </RangeScrollbar.Thumb>
  </RangeScrollbar.Root>
);