Ref API

Access imperative methods on the timeline instance via a React ref.

TempisTimelineRef

MethodSignatureDescription
focus(options?: FocusOptions) => voidFocus on an item, date, or range.
getRange() => { start: Date; end: Date }Get the current visible range.
setItems(items) => voidReplace all items.
getItems() => TempisTimelineItem[]Get current items.
setCategories(categories) => voidReplace all categories.
getCategories() => TempisTimelineCategory[]Get current categories.
setBands(bands) => voidReplace all bands.
setDependencies(deps) => voidReplace all dependencies.
setSelection(ids) => voidSet selected item IDs.
getSelection() => (string | number)[]Get selected item IDs.
clearSelection() => voidClear all selections.
setGroupCollapsed(group: string, collapsed?: boolean) => voidSet or toggle a group's collapsed state.
isGroupCollapsed(group: string) => booleanCheck if a group is collapsed.
toImage(options?) => Promise<Blob>Export as image.
redraw() => voidForce a redraw.
getInstance() => CoreTimeline | nullAccess the underlying core instance.
getCanvas() => HTMLCanvasElement | nullAccess the canvas element.

Usage Pattern

The component uses forwardRef and useImperativeHandle to expose the ref methods. Create a ref with useRef and pass it to the component.

The ref is null until the component mounts and the timeline instance is created. Always use optional chaining (ref.current?.focus(...)) when calling ref methods.

Example — Focus Buttons

import { useRef } from 'react';
import { TempisTimeline, type TempisTimelineRef } from '@tempis/react';

function App() {
  const timelineRef = useRef<TempisTimelineRef>(null);

  const items = [
    { id: 1, label: 'Item 1', start: '2026-01-05', end: '2026-01-19' },
    { id: 2, label: 'Item 2', start: '2026-01-20', end: '2026-02-02' },
    { id: 3, label: 'Item 3', start: '2026-02-05' },
  ];

  return (
    <div>
      <div style={{ marginBottom: 8 }}>
        <button onClick={() => timelineRef.current?.focus({ id: 1, animate: true })}>
          Focus Item 1
        </button>
        <button onClick={() => timelineRef.current?.focus({ id: 3, animate: true })}>
          Focus Item 3
        </button>
        <button onClick={() => timelineRef.current?.focus({ animate: true })}>
          Fit All
        </button>
      </div>
      <TempisTimeline
        ref={timelineRef}
        items={items}
        options={{
          responsive: true,
          range: { start: '2026-01-01', end: '2026-02-15', position: 'bottom' }
        }}
        height={300}
      />
    </div>
  );
}

Escape Hatches

getInstance() returns the underlying TempisTimeline core instance (or null before mount). getCanvas() returns the raw <canvas> element. Use these when you need functionality not exposed by the ref API.