@edux-design/timeline

Jira-style timeline / schedule surface for grouped work items. The initial package includes a sticky work column, date-range bars, a today marker, and a floating toolbar that is the only exposed zoom control.

Installation

pnpm add @edux-design/timeline @edux-design/buttons @edux-design/forms @edux-design/icons @edux-design/tooltips @edux-design/utils
# or
npm install @edux-design/timeline @edux-design/buttons @edux-design/forms @edux-design/icons @edux-design/tooltips @edux-design/utils

Usage

import { Timeline } from "@edux-design/timeline";

const groups = [
  {
    id: "releases",
    label: "Releases",
    items: [
      {
        id: "epm-226",
        title: "PDF export options and settings",
        start: "2026-02-10",
        end: "2026-04-23",
        milestones: [
          {
            id: "beta",
            date: "2026-03-12",
            label: "Beta",
            tone: "warning",
            tooltip: "Internal review milestone",
          },
          {
            id: "ship",
            date: "2026-04-23",
            label: "Ship",
            tone: "success",
            tooltip: "Production release target",
          },
        ],
      },
    ],
  },
];

export function Example() {
  return (
    <Timeline
      groups={groups}
      globalMilestones={[
        {
          id: "freeze",
          date: "2026-03-31",
          label: "Freeze",
          tone: "warning",
          tooltip: "Planning freeze",
        },
      ]}
      defaultZoom="quarters"
    />
  );
}

Resizable items

function Example() {
  const [groups, setGroups] = useState(data);

  return (
    <Timeline
      groups={groups}
      allowItemDrag
      allowItemResize
      onItemDatesChange={(itemId, nextRange, item) => {
        // update your state, call an API, dispatch an action, etc.
      }}
    />
  );
}

Props

groups (array, required)

Grouped timeline data.

zoom ("weeks" | "months" | "quarters")

Controlled zoom level.

globalMilestones (array)

Global vertical markers that span the entire timeline pane.

showCheckboxes (boolean, default false)

Renders form checkboxes before the expand chevron for each row.

selectedItemIds (array or Set)

Controlled selected row ids when checkboxes are shown.

defaultSelectedItemIds (array or Set)

Initial selected row ids for uncontrolled checkbox usage.

onSelectedItemIdsChange (function)

Called when a checkbox changes.

onSelectedItemIdsChange(nextSelectedIds, itemId, checked);

allowItemResize (boolean, default false)

Shows resize handles on timeline bars so users can adjust an item's date range.

allowItemDrag (boolean, default false)

Allows users to drag a timeline bar horizontally to move the whole range while keeping its duration.

onItemDatesChange (function)

Called after a resize or horizontal drag interaction completes.

onItemDatesChange(itemId, { start, end }, item);

• itemId is the resized row id.
• start and end are emitted as YYYY-MM-DD strings.
• item is the original item object being resized.

defaultZoom ("weeks" | "months" | "quarters", default "quarters")

Initial zoom level for uncontrolled usage.

onZoomChange (function)

Called when the floating toolbar changes zoom.

availableZoomLevels (array)

Subset of zoom levels to show in the toolbar.

leftColumnWidth (number, default 420)

Width of the sticky work column in pixels.

showTodayMarker (boolean, default true)

Shows a vertical marker for today.

autoScrollToToday (boolean, default true)

Centers today when the component mounts or the zoom level changes.

Milestones

Each item can define a milestones array. Milestones render as markers anchored to a specific date on that row.

milestones: [
  {
    id: "ship",
    date: "2026-04-23",
    label: "Ship",
    tone: "success",
    showLabel: true,
    tooltip: "Production release target",
    tooltipSide: "top",
  },
];

• date is required and accepts YYYY-MM-DD or Date.
• tone supports primary, success, warning, danger, and neutral.
• showLabel defaults to true when a label or tooltip string exists.
• tooltip accepts any React node and renders through @edux-design/tooltips.
• tooltipSide maps directly to the tooltip package placement API.

Global milestones

Use globalMilestones when a marker should span the whole schedule instead of a single row.

globalMilestones: [
  {
    id: "freeze",
    date: "2026-03-31",
    label: "Freeze",
    tone: "warning",
    tooltip: "Planning freeze",
    tooltipSide: "top",
  },
];

• Global milestones use the same field shape as row milestones.
• They render as full-height vertical markers inside the timeline pane.
• Labels and tooltips stay attached to the marker head at the top of the grid.

Notes

• Zoom changes are intentionally limited to the floating toolbar.
• The current version is optimized for schedule display and review rather than editing or drag-to-resize.
• Dates accept YYYY-MM-DD strings or Date objects.