TimelineProvider

Timelinx has two provider exports with the same component name. They serve related but different layers.

Provider Choice

Most UI apps should use the UI provider. TimelineEditor, TimelineTrack, TimelineRuler, panels, and other UI components expect the UI context because they need zoom and layout information in addition to the engine.

Headless React Provider

import { TimelineEngine, TimelineProvider } from '@timelinx/react';

const engine = new TimelineEngine({ initialState });

export function App() {
  return (
    <TimelineProvider engine={engine}>
      <CustomTimeline />
    </TimelineProvider>
  );
}

Use this provider for your own components with hooks from @timelinx/react.

UI Provider

import { TimelineEngine } from '@timelinx/react';
import { TimelineEditor, TimelineProvider } from '@timelinx/ui';

const engine = new TimelineEngine({
  initialState,
  getPixelsPerFrame: () => 4,
});

export function App() {
  return (
    <TimelineProvider
      engine={engine}
      initialPpf={4}
      labelWidth={176}
      rulerHeight={28}
      toolbarHeight={42}
    >
      <TimelineEditor />
    </TimelineProvider>
  );
}

The UI provider exposes:

• engine
• ppf and setPpf
• scrollLeft and setScrollLeft
• vpWidth and setVpWidth
• labelWidth
• rulerHeight
• toolbarHeight

These values keep the ruler, playhead, clips, track labels, and scroll container aligned.

MediaAssetsProvider

@timelinx/ui also exposes MediaAssetsProvider for media import and preview workflows.

import {
  MediaAssetsProvider,
  TimelineEditor,
  TimelineProvider,
} from '@timelinx/ui';

export function App() {
  return (
    <MediaAssetsProvider>
      <TimelineProvider engine={engine}>
        <TimelineEditor />
      </TimelineProvider>
    </MediaAssetsProvider>
  );
}

Use it around editor surfaces that need imported media metadata, preview records, or drop-zone flows.

Engine Lifetime

Create the engine outside render or memoize it. Recreating it on every render resets history, tool state, selected IDs, indexes, and subscribers.

const engine = useMemo(
  () => new TimelineEngine({ initialState }),
  [initialState],
);

If initialState is loaded asynchronously, create the engine after loading completes and render a loading state until it exists.