Gantt

A Gantt chart component with drag-and-drop task scheduling, timeline zoom, custom markers, and sidebar navigation.

Client Only

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-gantt

UI Primitives(2 components)

npx shadcn@latest add card context-menu

Required Packages(4 packages)

pnpm add @dnd-kit/core @dnd-kit/modifiers date-fns lodash

Usage

import {
  GanttProvider,
  GanttSidebar,
  GanttSidebarHeader,
  GanttSidebarGroup,
  GanttSidebarItem,
  GanttHeader,
  GanttContentHeader,
  GanttTimeline,
  GanttFeatureList,
  GanttFeatureListGroup,
  GanttFeatureRow,
  GanttFeatureItem,
  GanttFeatureItemCard,
  GanttFeatureDragHelper,
  GanttColumns,
  GanttColumn,
  GanttAddFeatureHelper,
  GanttToday,
  GanttMarker,
  GanttCreateMarkerTrigger
} from '@docyrus/ui/components/gantt';
import type { GanttFeature, GanttStatus, Range } from '@docyrus/ui/components/gantt';

const statuses: GanttStatus[] = [
  { id: 'todo', name: 'To Do', color: '#3b82f6' },
  { id: 'in-progress', name: 'In Progress', color: '#f59e0b' },
  { id: 'done', name: 'Done', color: '#22c55e' }
];

const features: GanttFeature[] = [
  {
    id: '1',
    name: 'Design system',
    startAt: new Date(2025, 0, 1),
    endAt: new Date(2025, 0, 15),
    status: statuses[0]
  }
];

<GanttProvider>
  <GanttSidebar>
    <GanttSidebarHeader>Tasks</GanttSidebarHeader>
    <GanttSidebarGroup name="Sprint 1">
      {features.map(f => (
        <GanttSidebarItem key={f.id} feature={f} />
      ))}
    </GanttSidebarGroup>
  </GanttSidebar>

  <div className="flex flex-col flex-1">
    <GanttHeader>
      <GanttContentHeader />
    </GanttHeader>

    <GanttTimeline>
      <GanttColumns>
        {columns.map(col => (
          <GanttColumn key={col.id} {...col} />
        ))}
      </GanttColumns>
      <GanttFeatureList>
        <GanttFeatureListGroup>
          {features.map(f => (
            <GanttFeatureRow key={f.id} feature={f}>
              <GanttFeatureItem feature={f}>
                <GanttFeatureItemCard feature={f} />
              </GanttFeatureItem>
            </GanttFeatureRow>
          ))}
        </GanttFeatureListGroup>
      </GanttFeatureList>
      <GanttToday />
    </GanttTimeline>
  </div>

  <GanttFeatureDragHelper />
</GanttProvider>

Components

Component	Description
`GanttProvider`	Root context provider. Manages zoom, range, scroll, and drag state.
`GanttSidebar`	Left sidebar container for task list navigation.
`GanttSidebarHeader`	Sidebar header area.
`GanttSidebarGroup`	Named group within the sidebar.
`GanttSidebarItem`	Single task row in the sidebar.
`GanttHeader`	Top header container area.
`GanttContentHeader`	Timeline column headers (year/month/day labels based on range).
`GanttTimeline`	Scrollable timeline area with DnD support.
`GanttFeatureList`	Container for feature rows.
`GanttFeatureListGroup`	Group within the feature list.
`GanttFeatureRow`	Row container for a single feature.
`GanttFeatureItem`	Draggable feature bar within a row.
`GanttFeatureItemCard`	Visual card for the feature (colored by status).
`GanttFeatureDragHelper`	Drag preview overlay during drag operations.
`GanttColumns`	Background column grid for the timeline.
`GanttColumn`	Single column in the grid.
`GanttAddFeatureHelper`	Quick-add button that appears on column hover.
`GanttToday`	Today marker line on the timeline.
`GanttMarker`	Custom timeline marker (milestones, deadlines).
`GanttCreateMarkerTrigger`	Button to create a new marker at a date.

API Reference

GanttProvider

Prop	Type	Default	Description
`zoom`	`number`	—	Zoom level controlling column density.
`range`	`Range`	—	Timeline granularity (`'daily'`, `'monthly'`, `'quarterly'`).
`columnWidth`	`number`	—	Pixel width per column.
`sidebarWidth`	`number`	—	Sidebar width in pixels.
`headerHeight`	`number`	—	Header height in pixels.
`rowHeight`	`number`	—	Row height in pixels.
`onAddItem`	`(date: Date) => void`	—	Called when quick-add is triggered.
`placeholderLength`	`number`	—	Default duration for new tasks.
`timelineData`	`TimelineData`	—	Date structure for timeline columns.

GanttSidebarGroup

Prop	Type	Default	Description
`name`	`string`	—	Group label displayed in the sidebar.
`className`	`string`	—	Additional CSS classes.

GanttSidebarItem

Prop	Type	Default	Description
`feature`	`GanttFeature`	—	Task data to display.
`className`	`string`	—	Additional CSS classes.

GanttFeatureItem

Prop	Type	Default	Description
`feature`	`GanttFeature`	—	Task data for positioning and drag.
`selected`	`boolean`	—	Highlight state.
`onSelect`	`(feature: GanttFeature) => void`	—	Selection callback.
`onDragEnd`	`(feature: GanttFeature, delta: Date) => void`	—	Called after drag with new date.

GanttFeatureItemCard

Prop	Type	Default	Description
`feature`	`GanttFeature`	—	Task data (status color, name).
`className`	`string`	—	Additional CSS classes.

GanttMarker

Prop	Type	Default	Description
`id`	`string`	—	Unique marker identifier.
`date`	`Date`	—	Marker position on the timeline.
`label`	`string`	—	Marker label text.
`className`	`string`	—	Additional CSS classes.

Type Reference

GanttFeature

Field	Type	Description
`id`	`string`	Unique identifier.
`name`	`string`	Task name.
`startAt`	`Date`	Task start date.
`endAt`	`Date`	Task end date.
`status`	`GanttStatus`	Current status with color.
`lane`	`string`	Optional lane/swimlane identifier.

GanttStatus

Field	Type	Description
`id`	`string`	Unique identifier.
`name`	`string`	Display name.
`color`	`string`	Hex color for the status.

Range

'daily' | 'monthly' | 'quarterly'

TimelineData

type TimelineData = Array<{
  year: number;
  quarters: Array<{
    months: Array<{ days: number }>;
  }>;
}>;

Gantt

On this page