Plugin Timeline

Timeline component with vertical, horizontal, and Gantt-style layouts for displaying events and project timelines.

Installation

npm install @object-ui/plugin-timeline

The props an object-timeline node reads on a page are generated from the spec into the component reference; this page covers using the plugin from React.

Usage

Basic Usage

// Import once in your app entry point
import '@object-ui/plugin-timeline'
import type { TimelineSchema } from '@object-ui/types'

// Use in schemas - Vertical Timeline
const schema: TimelineSchema = {
  type: 'timeline',
  variant: 'vertical',
  items: [
    {
      time: '2024-01-15',
      title: 'Project Started',
      description: 'Kickoff meeting',
      variant: 'success'
    }
  ]
}

Features

• Three Layout Variants: Vertical, horizontal, and Gantt-style layouts
• Customizable Markers: Color-coded markers with icon support
• Date Formatting: Multiple date format options
• Gantt Charts: Project timeline visualization with task bars
• Time Scales: Hour, day, week, month, quarter, or year scales for Gantt view
• Lightweight: Pure CSS and React components

Properties

Every key above is declared on the exported TimelineSchema, so an editor completes them and a wrong value is a type error. scale is the canonical axis key and the only one — it is @objectstack/spec's ui/TimelineConfig.json spelling and the one the renderer reads.

Object-bound timeline (object-timeline)

object-timeline fetches records from objectName and draws one entry per record, from the fields its timeline config names. An authored node takes its props in the properties bag, where @objectstack/spec's ComponentPropsMap['object-timeline'] row declares them:

{
  "type": "object-timeline",
  "properties": {
    "objectName": "project_task",
    "timeline": { "startDateField": "start_date", "titleField": "name" },
    "navigation": { "mode": "drawer" }
  }
}

Where the entries come from

The first record source present wins: items (authored entries, drawn as written), then data (pre-fetched records), then a bind path, then the query on objectName. Only the query is a fetch, so objectName is optional: a timeline drawn from items, data or a bind path needs none to draw (entry-click navigation still reads it, below), and a node-level dataSource binding can supply the object instead. Records, from data, a bind path or the query, are composed into entries through the field bindings below; authored items are not.

Entry-click navigation

navigation is what an entry click opens — the spec's NavigationConfig by reference, ViewNavigationConfig in @object-ui/types, the type ObjectGridSchema.navigation uses: mode (drawer, page, new_window or none) with size, openNewTab and preventNavigation.

A click handler from a parent view outranks the whole key.

Variants

Marker Variants

Available marker/bar colors:

• default - Gray
• success - Green
• info - Blue
• warning - Yellow
• danger - Red

const item = {
  time: '2024-01-15',
  title: 'Important Milestone',
  variant: 'success'  // Green marker
}

Date Formatting

The timeline component supports three date formats:

import type { TimelineSchema } from '@object-ui/types'

const short: TimelineSchema['dateFormat'] = 'short'  // "1/15/2024"
const long: TimelineSchema['dateFormat'] = 'long'    // "January 15, 2024"
const iso: TimelineSchema['dateFormat'] = 'iso'      // "2024-01-15"

A date-only value (2024-01-15) names a calendar day, so every face prints that day in every viewer's time zone, and the object timeline buckets and sorts it as that day. A value with a time part is an instant: short and long print its day in the viewer's zone, and iso prints its UTC day.

Without a groupByField, the object timeline groups entries into date buckets (Earlier, Today, Tomorrow, This week, Next week, Later, No date). "This week" starts on the first day of the week of the user's display locale, the day the calendar's weeks start on: Sunday under en-US, Monday under en-GB or zh-CN.

Time Scales (Gantt)

For Gantt-style timelines, choose the appropriate time scale:

import type { TimelineSchema } from '@object-ui/types'

const shortProject: TimelineSchema['scale'] = 'day'    // short projects
const mediumProject: TimelineSchema['scale'] = 'week'  // medium projects
const longProject: TimelineSchema['scale'] = 'month'   // long projects

A date-only bar date, minDate or maxDate (2024-01-15) names a calendar day, so the axis headers, the bar positions and the bar tooltips all place it on that day in every viewer's time zone. A value with a time part is an instant and sits at its hour in the viewer's day. A plan with no bar dates and no pinned range shows a one-day axis on the viewer's today.

The headers and the bars share one axis. It runs from the start of the unit that holds the first date to the end of the unit that holds the last. Each header is as wide as its unit is long: hour, day and week columns are equal, and a month is as wide as its days. So a bar lines up under the header of the unit it starts in.

Customization

Custom Icons

const item = {
  time: '2024-01-15',
  title: 'Milestone',
  icon: '🎯',  // Any emoji or short text
  variant: 'success'
}

Custom Colors

Use Tailwind CSS classes for additional styling:

import type { TimelineSchema } from '@object-ui/types'

const schema: TimelineSchema = {
  type: 'timeline',
  variant: 'vertical',
  className: 'max-w-4xl mx-auto',
  items: [
    { time: '2024-01-15', title: 'Milestone', variant: 'success' }
  ]
}

TypeScript Support

import type { TimelineSchema } from '@object-ui/types'

const timelineSchema: TimelineSchema = {
  type: 'timeline',
  variant: 'vertical',
  items: [
    {
      time: '2024-01-15',
      title: 'Event',
      description: 'Description',
      variant: 'success'
    }
  ]
}

Related Documentation

• Plugin System Overview
• Package README