Timeline Canvas
  • English

    • Getting Started

    Timeline Canvas is a high-performance, plugin-driven Canvas timeline component. It uses a seconds-based relative time model (all times are offsets in seconds from the start).

    Basic Usage

    Minimal runnable flow: create a canvas → initialize Timeline → load data → (optional) load plugins.

    1. Install

    npm install timeline-canvas
# or
yarn add timeline-canvas
# or
pnpm add timeline-canvas

    2. Create a Canvas

    <canvas id="timelineCanvas" style="width: 100%; height: 600px;"></canvas>

    3. Initialize the Timeline (Seconds-based)

    import { Timeline } from "timeline-canvas";

const timeline = new Timeline("timelineCanvas", {
  startTime: 0,
  endTime: 3600,
  canvasHeight: 600,
  trackHeight: 46,
  trackMargin: 10,
});

    4. Load Data (Seconds-based)

    timeline.loadData({
  tracks: [
    {
      events: [
        {
          startTime: 0,
          endTime: 900,
          title: "Frontend Development",
          description: "Build the UI",
        },
      ],
    },
    {
      events: [
        {
          startTime: 1800,
          endTime: 2700,
          title: "Design Review",
          description: "UI/UX design review meeting",
        },
      ],
    },
  ],
});

    5. Add Plugins (Optional)

    usePlugin() returns Promise<boolean> to indicate whether the plugin was loaded successfully.

    import {
  ContextMenuPlugin,
  LightThemePlugin,
  PerformanceOverlayPlugin,
} from "timeline-canvas/plugins";

timeline.config.enableContextMenu = true;
timeline.config.contextMenuItems = [
  { type: "detail", name: "View details" },
  { type: "delete", name: "Delete" },
];

await timeline.usePlugin(LightThemePlugin);
await timeline.usePlugin(PerformanceOverlayPlugin);
await timeline.usePlugin(ContextMenuPlugin());

    Further Reading

    Architecture Overview (Optional)

    Using MCP in VS Code (Optional)

    If you use VS Code + Copilot Chat and want AI to help via tool calls (e.g., generating plugin scaffolding, running validations, or triggering allowlist scripts), see:

    Full Example (Seconds-based, Same as the Demo)

    <!DOCTYPE html>
<html>
<head>
  <title>Timeline Canvas Example</title>
  <style>
    #timeline-container {
      width: 100%;
      height: 600px;
      border: 1px solid #ccc;
    }
  </style>
</head>
<body>
  <canvas id="timelineCanvas"></canvas>

  <script type="module">
    import { Timeline } from 'timeline-canvas';
    import {
      ContextMenuPlugin,
      LightThemePlugin,
      PerformanceOverlayPlugin,
    } from 'timeline-canvas/plugins';

    const timeline = new Timeline('timelineCanvas', {
      startTime: 0,
      endTime: 3600,
      enableContextMenu: true,
      contextMenuItems: [
        { type: 'detail', name: 'View details' },
        { type: 'delete', name: 'Delete' },
      ],
    });

    // Load sample data (seconds-based)
    timeline.loadData({
      tracks: [{ events: [{ startTime: 0, endTime: 900, title: 'Phase 1 Development' }] }]
    });

    // Add plugins
    await timeline.usePlugin(LightThemePlugin);
    await timeline.usePlugin(PerformanceOverlayPlugin);
    await timeline.usePlugin(ContextMenuPlugin());

    // Switch theme at runtime
    // Switch to dark theme
    setTimeout(() => void timeline.setTheme('dark'), 1000);
  </script>
</body>
</html>