PlTimelineChart

Work against time, a row per thing, a bar per stretch of it. The two axes are a set of rows and a calendar.

React

import { PlTimelineChart } from 'plass-ui';

<PlTimelineChart series={plan} />;

import 'package:plass_ui/plass_ui.dart';

PlTimelineChart(series: plan);

This is a bar chart turned on its side with the baseline taken away: every bar starts where its own data says rather than at zero, so what the chart is about is when rather than how much.

Not to be confused with PlTimeline, which is a list of steps and draws no axis at all. That one is for a sequence of events; this one is for how long each of them took.

Props

Prop	Type	Default	Description
series *	readonly PlassTimelineSeries[]	—	One row per series, and the spans on it. A row's name is what the axis says down the side
min	PlassChartCategory	—	Where the time axis starts. Taken from the spans otherwise, rounded outward to a date a calendar names
max	PlassChartCategory	—	And where it ends
barSize	number	—	How thick a bar may get. Above the cap the leftover stays as air
rounded	boolean	true	Cuts the corners off both ends, unlike a bar chart: neither end of a span is a zero
xAxis	PlassChartAxis	—	The axis the rows are named down
yAxis	PlassChartAxis	—	The time axis
tooltip	PlassChartTooltip	—	The tooltip
height	number | string	—	How tall the plot is
label	string	'Chart'	What the whole drawing is called
empty	ReactNode	—	What is drawn when there is nothing to draw
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Type scale, plot height and the bar thickness cap
densityshared	'default' | 'compact'	'default'	How much of a row's slot the bars on it may take. Never the height

Prop	Type	Default	Description
series *	List<PlassTimelineSeries>	—	One row per series, and the spans on it. A row's name is what the axis says down the side
min	PlassChartCategory?	—	Where the time axis starts. Taken from the spans otherwise, rounded outward to a date a calendar names
max	PlassChartCategory?	—	And where it ends
barSize	double?	—	How thick a bar may get. Above the cap the leftover stays as air
rounded	bool	true	Cuts the corners off both ends, unlike a bar chart: neither end of a span is a zero
xAxis	PlChartAxis	PlChartAxis()	The axis the rows are named down
yAxis	PlChartAxis	PlChartAxis()	The time axis
tooltip	PlChartTooltip	PlChartTooltip()	The tooltip
height	double?	—	How tall the plot is
semanticLabel	String?	'Chart'	What the whole drawing is called
empty	Widget?	—	What is drawn when there is nothing to draw
sizeshared	PlassSize	PlassSize.md	Type scale, plot height and the bar thickness cap
densityshared	PlassDensity	PlassDensity.standard	How much of a row's slot the bars on it may take. Never the height

A row is a series (one entity, one name, one colour), but its data are spans rather than values, so it takes PlassTimelineSeries rather than the usual series type. There is no legend and no hidden: the rows are the category axis, already named down the side, and a twenty-entry legend restating them adds nothing.

The time axis ticks where a calendar ticks. The 1-2-5 family that rounds a value axis is the wrong one for an instant, run on milliseconds it produces a tick every 200,000,000 ms, which lands at 14:53:20 on an arbitrary Tuesday.

Examples

Overlapping spans

React

import { PlTimelineChart } from 'plass-ui';

const hour = (h: number) => new Date(2026, 0, 5, h);

const rooms = [
  {
    name: 'Studio A',
    data: [
      { start: hour(9), end: hour(12), label: 'Standup' },
      { start: hour(10), end: hour(14), label: 'Workshop' },
      { start: hour(15), end: hour(18), label: 'Review' }
    ]
  },
  {
    name: 'Studio B',
    data: [{ start: hour(11), end: hour(17), label: 'Recording' }]
  }
];

export default function TimelineChartLanes() {
  return <PlTimelineChart className="w-full" label="Room bookings" series={rooms} height={180} />;
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

PlassChartCategory _hour(int h) => PlassChartCategory.date(DateTime(2026, 1, 5, h));

final List<PlassTimelineSeries> _rooms = <PlassTimelineSeries>[
  PlassTimelineSeries(
    name: 'Studio A',
    data: <PlassTimelinePoint>[
      PlassTimelinePoint(start: _hour(9), end: _hour(12), label: 'Standup'),
      PlassTimelinePoint(start: _hour(10), end: _hour(14), label: 'Workshop'),
      PlassTimelinePoint(start: _hour(15), end: _hour(18), label: 'Review'),
    ],
  ),
  PlassTimelineSeries(
    name: 'Studio B',
    data: <PlassTimelinePoint>[
      PlassTimelinePoint(start: _hour(11), end: _hour(17), label: 'Recording'),
    ],
  ),
];

class TimelineChartLanes extends StatelessWidget {
  const TimelineChartLanes({super.key});

  @override
  Widget build(BuildContext context) {
    return PlTimelineChart(series: _rooms, height: 180, semanticLabel: 'Room bookings');
  }
}

A row that is doing two things at once is the ordinary case, and drawing the second bar on top of the first turns two facts into one smudge. Overlapping spans are moved onto lanes of their own, by the greedy packing every scheduler uses: walk the spans in start order and drop each into the first lane whose last one has finished.

A row with no overlaps stays in a single lane, so the common row is exactly as thick as it was. Lanes are assigned in start order but stored against the span's original index, because the order the data was written in is the order the arrow keys walk and a layout decision must not reshuffle it.

min and max

React

import { PlTimelineChart } from 'plass-ui';

const day = (n: number) => new Date(2026, 0, n);

const work = [
  { name: 'Migration', data: [{ start: day(-40), end: day(24), label: 'Data migration' }] },
  { name: 'Rewrite', data: [{ start: day(5), end: day(70), label: 'Service rewrite' }] }
];

export default function TimelineChartWindow() {
  return (
    <PlTimelineChart
      className="w-full"
      label="This quarter"
      series={work}
      min={day(1)}
      max={day(31)}
      height={140}
    />
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

PlassChartCategory _day(int n) => PlassChartCategory.date(DateTime(2026, 1, n));

final List<PlassTimelineSeries> _work = <PlassTimelineSeries>[
  PlassTimelineSeries(
    name: 'Migration',
    data: <PlassTimelinePoint>[
      PlassTimelinePoint(start: _day(-40), end: _day(24), label: 'Data migration'),
    ],
  ),
  PlassTimelineSeries(
    name: 'Rewrite',
    data: <PlassTimelinePoint>[
      PlassTimelinePoint(start: _day(5), end: _day(70), label: 'Service rewrite'),
    ],
  ),
];

class TimelineChartWindow extends StatelessWidget {
  const TimelineChartWindow({super.key});

  @override
  Widget build(BuildContext context) {
    return PlTimelineChart(
      series: _work,
      min: _day(1),
      max: _day(31),
      height: 140,
      semanticLabel: 'This quarter',
    );
  }
}

A span is cut to the plot rather than to the data. A caller who pinned the axis to this quarter still has work that began last one, and a bar that stops at the edge says there is more of it off the side; one drawn past the edge says the axis is wrong.

A zero-width span keeps a hairline, so a milestone is still something on the row.

rounded

Both ends, unlike a bar chart, where the baseline end stays square. A span grows from nothing: neither of its ends is a zero, so neither is the one the reader is measuring from.

Accessibility

• The drawing carries the chart's name, and every span is handed over as text: each row, then its spans as the two instants they run between.
• On React the picture is a role="img" and a tab stop, and the arrow keys walk the spans in the order the data was written.
• On React the same data is written into a table under the chart, a row per span rather than the grid every other chart uses. Two rows of a Gantt have no columns in common: the third thing on one row and the third thing on another are unrelated, and filing them side by side would invent a relationship.
• A span that names itself is named in the readout, with its row on the second line rather than repeated on the first.