Canvas Timeline
Function

useActiveLayers

Returns active timeline layers at a timeline time.

Usage notes

The hook is collection-first: each named layer returns every matching active clip in stable track order. `primary` is only a convenience first match. Use it for preview panels, custom media status, subtitle overlays, and diagnostics that need to inspect which timeline clips are active without starting playback. For transport controls that drive an external media clock, compose useTimelineMediaSync or useTimelineMediaPlayback instead.

Signature

Type Definition
useActiveLayers(options: ActiveLayerOptions<LayerName>): ActiveLayerResult<LayerName>

Type parameters

NameConstraintDefaultDescription
LayerNamestringstringNamed layer keys inferred from `options.layers`, such as `"visuals" | "audio"`.

Parameters

NameTypeDescription
optionsActiveLayerOptions<LayerName>Active layer selectors and optional lookup time.

Returns

ActiveLayerResult<LayerName>

Active clips grouped by the configured layer selectors.

Examples

tsx Example
import { useMemo } from 'react';
import { useActiveLayers } from '#react/hooks';


const previewLayers = {
  visuals: { trackKind: 'visual' },
  audio: { trackKind: 'audio' },
} as const;


export function ActiveMediaReadout() {
  const layers = useMemo(() => previewLayers, []);
  const activeLayers = useActiveLayers({ layers });


  return (
    <dl>
      <dt>Visual</dt>
      <dd>{activeLayers.primary.visuals?.clip.name ?? 'No visual clip'}</dd>
      <dt>Audio clips</dt>
      <dd>{activeLayers.layers.audio.length}</dd>
    </dl>
  );
}

Related links