PlTimeline

A sequence of steps, in the order they happen in. active says how far along it is, and the timeline works out what each step's bullet should be.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

<PlTimeline active={2}>
  <PlTimelineItem title="Ordered" meta="Mon 09:12" bullet="1" />
  <PlTimelineItem title="Packed" meta="Mon 14:40" bullet="2" />
  <PlTimelineItem title="Shipped" meta="Tue 07:05" bullet="3" />
</PlTimeline>;

import 'package:plass_ui/plass_ui.dart';

const PlTimeline(
  active: 2,
  items: <PlTimelineItem>[
    PlTimelineItem(title: Text('Ordered'), meta: Text('Mon 09:12'), bullet: Text('1')),
    PlTimelineItem(title: Text('Packed'), meta: Text('Mon 14:40'), bullet: Text('2')),
    PlTimelineItem(title: Text('Shipped'), meta: Text('Tue 07:05'), bullet: Text('3')),
  ],
);

Props

Prop	Type	Default	Description
active	number	—	The index of the item being worked on now. Everything before it is complete, everything after still to come. An index rather than a value, because a timeline has no selection — nothing is chosen, and the only question is how far reality has got
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	Bullet diameter and type scale
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	The gradient in the bullets and the family the connectors take
densityshared	'default' | 'compact'	'default'	Spacing between items only. Never the type scale, never the bullet
orientationshared	PlassResponsive<'horizontal' | 'vertical'>	'vertical'	Which way the sequence runs. vertical takes any number of steps with anything to say about each; horizontal is the stepper across the top of a checkout, honest only while every label is short
render	useRender.RenderProp	—	Renders something other than an ol
children	ReactNode	—	The PlTimelineItems

Prop	Type	Default	Description
items *	List<PlTimelineItem>	—	The steps, as a list of descriptions rather than children — which step is complete is arithmetic on an index, and the last connector has to know it is the last
active	int?	—	The index of the item being worked on now. Everything before it is complete, everything after still to come. An index rather than a value, because a timeline has no selection — nothing is chosen, and the only question is how far reality has got
sizeshared	PlassSize	PlassSize.md	Bullet diameter and type scale
colorshared	PlassColor	PlassColor.primary	The gradient in the bullets and the family the connectors take
densityshared	PlassDensity	PlassDensity.standard	Spacing between items only. Never the type scale, never the bullet
orientationshared	PlassResponsive<PlassOrientation>	PlassOrientation.vertical	Which way the sequence runs. vertical takes any number of steps with anything to say about each; horizontal is the stepper across the top of a checkout, honest only while every label is short

Every native <ol> attribute passes straight through. color is excluded from the pass-through because it is a Plass prop here.

The steps are items rather than children, and a PlTimelineItem is a description rather than a widget, the same call PlBreadcrumb makes, and Flutter's own idiom. Which step is complete is arithmetic on an index, and the last step's connector has to know it is the last; neither question can be asked of an opaque Widget.

There is no variant and no elevation: a timeline is a run of marks down the page, not a sheet laid on it. Put one inside a PlCard when it needs a surface.

PlTimelineItem

Prop	Type	Default	Description
title	ReactNode	—	The heading of this step
meta	ReactNode	—	When it happened — a date, a duration, a name. Beside the title on a wide item, under it on a narrow one
bullet	ReactNode	—	What goes inside the bullet: a number, an icon, an avatar. Omit it and the bullet is a plain disc, which is what a step with nothing to say about itself should be
status	'complete' | 'current' | 'upcoming'	—	Overrides what the timeline’s active would have computed for this item — a step that failed and stopped the sequence, a step that was skipped
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	—	Overrides the timeline’s colour family for this item alone
connector	'solid' | 'dashed' | 'dotted' | 'none'	'solid'	How the line to the next item is drawn. The last item’s line is never drawn anyway
children	ReactNode	—	The body of the step

Prop	Type	Default	Description
title	Widget?	—	The heading of this step
meta	Widget?	—	When it happened — a date, a duration, a name. Beside the title on a wide item, under it on a narrow one
bullet	Widget?	—	What goes inside the bullet: a number, an icon, an avatar. Omit it and the bullet is a plain disc, which is what a step with nothing to say about itself should be
status	PlTimelineStatus?	—	Overrides what the timeline’s active would have computed for this item — a step that failed and stopped the sequence, a step that was skipped
colorshared	PlassColor?	—	Overrides the timeline’s colour family for this item alone
connector	PlTimelineConnector	PlTimelineConnector.solid	How the line to the next item is drawn. The last item’s line is never drawn anyway
child	Widget?	—	The body of the step

Every native <li> attribute passes straight through. size, density and orientation are inherited from the PlTimeline around it.

An item's index is not a property and cannot be. An item that had to be told where it was in the list would be an item every caller could put in the wrong place, and active would stop meaning anything. The timeline numbers its steps as it walks them.

What the shared axes (size color density orientation) mean across the library is in prop conventions.

Examples

active

An index rather than a value, because a timeline has no selection. Nothing here is chosen, and the only question is how far down the list reality has reached. Omit it and every item is upcoming; pass the item count to mark the whole sequence done.

React

import { useState } from 'react';
import { PlButton, PlTimeline, PlTimelineItem } from 'plass-ui';

const steps = ['Account', 'Payment', 'Review', 'Done'];

export default function TimelineActive() {
  const [active, setActive] = useState(1);

  return (
    <div className="flex w-full max-w-md flex-col gap-5">
      <PlTimeline active={active}>
        {steps.map((step) => (
          <PlTimelineItem key={step} title={step} />
        ))}
      </PlTimeline>

      <div className="flex gap-2">
        <PlButton
          size="sm"
          variant="glass"
          color="secondary"
          onClick={() => setActive(Math.max(0, active - 1))}
        >
          Back
        </PlButton>
        <PlButton size="sm" onClick={() => setActive(Math.min(steps.length, active + 1))}>
          Next
        </PlButton>
      </div>
    </div>
  );
}

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

const List<String> _steps = <String>['Account', 'Payment', 'Review', 'Done'];

class TimelineActive extends StatefulWidget {
  const TimelineActive({super.key});

  @override
  State<TimelineActive> createState() => _TimelineActiveState();
}

class _TimelineActiveState extends State<TimelineActive> {
  int _active = 1;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 448,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 20,
        children: <Widget>[
          PlTimeline(
            active: _active,
            items: <PlTimelineItem>[for (final step in _steps) PlTimelineItem(title: Text(step))],
          ),
          Row(
            mainAxisSize: MainAxisSize.min,
            spacing: 8,
            children: <Widget>[
              PlButton(
                size: PlassSize.sm,
                variant: PlassVariant.glass,
                color: PlassColor.secondary,
                onPressed: () => setState(() => _active = _active <= 0 ? 0 : _active - 1),
                child: const Text('Back'),
              ),
              PlButton(
                size: PlassSize.sm,
                onPressed: () => setState(
                  () => _active = _active >= _steps.length ? _steps.length : _active + 1,
                ),
                child: const Text('Next'),
              ),
            ],
          ),
        ],
      ),
    );
  }
}

status

Three states rather than two, because "the one you are on" is not the same claim as "done", and a sequence that cannot say which step is current is a list.

Each state is a different axis, never a different opacity: complete is the family's gradient, current is that gradient with a halo of the soft tint around it, and upcoming is a hairline ring on the page's own surface. A reader who cannot tell the colours apart still has a filled shape, a haloed shape and an empty one.

status on an item overrides what active computed for it, a step that failed and stopped the sequence, a step that was skipped.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineStatus() {
  return (
    <PlTimeline className="w-full max-w-md" active={3}>
      <PlTimelineItem title="Cloned" bullet="1" />
      <PlTimelineItem title="Installed" bullet="2" />
      <PlTimelineItem title="Tested" bullet="✕" status="upcoming" color="danger">
        Two tests are red, so this step never finished.
      </PlTimelineItem>
      <PlTimelineItem title="Deployed" bullet="4" />
    </PlTimeline>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 448,
      child: PlTimeline(
        active: 3,
        items: <PlTimelineItem>[
          PlTimelineItem(title: Text('Cloned'), bullet: Text('1')),
          PlTimelineItem(title: Text('Installed'), bullet: Text('2')),
          PlTimelineItem(
            title: Text('Tested'),
            bullet: Text('✕'),
            status: PlTimelineStatus.upcoming,
            color: PlassColor.danger,
            child: Text('Two tests are red, so this step never finished.'),
          ),
          PlTimelineItem(title: Text('Deployed'), bullet: Text('4')),
        ],
      ),
    );
  }
}

connector

The line is drawn as one border edge rather than as a filled <div>, so dashed and dotted are the browser's own dashes and land on the device pixel grid the way every other edge in the library does.

Flutter's BorderSide has no dashes, so the line is painted: dashed and dotted are runs laid down by hand, at the same weight the solid one is drawn at. A dot is a round cap on a zero-length run, which is what makes it a circle rather than a short square.

It belongs to the item it leaves rather than the one it arrives at, which is what lets its colour say whether that step has been reached. The last item's line is never drawn. It would run off the end of the sequence into nothing.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineConnectors() {
  return (
    <PlTimeline className="w-full max-w-md" density="compact" active={4}>
      <PlTimelineItem title="solid" connector="solid" />
      <PlTimelineItem title="dashed" connector="dashed" />
      <PlTimelineItem title="dotted" connector="dotted" />
      <PlTimelineItem title="none" connector="none" />
      <PlTimelineItem title="The last line is never drawn" />
    </PlTimeline>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 448,
      child: PlTimeline(
        density: PlassDensity.compact,
        active: 4,
        items: <PlTimelineItem>[
          PlTimelineItem(title: Text('solid')),
          PlTimelineItem(title: Text('dashed'), connector: PlTimelineConnector.dashed),
          PlTimelineItem(title: Text('dotted'), connector: PlTimelineConnector.dotted),
          PlTimelineItem(title: Text('none'), connector: PlTimelineConnector.none),
          PlTimelineItem(title: Text('The last line is never drawn')),
        ],
      ),
    );
  }
}

orientation

vertical is the default and the one that takes an arbitrary number of steps with an arbitrary amount to say about each. horizontal is the stepper across the top of a checkout, and it is only honest while every label is short.

It is responsive, so a set can run one way on a phone and the other on a laptop. A server renders the xs entry and the browser corrects it on hydration.It is resolved against the window's width during build, so the first frame is already right. See breakpoints.

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineOrientation() {
  return (
    <PlTimeline className="w-full max-w-lg" orientation="horizontal" active={1}>
      <PlTimelineItem title="Account" bullet="1" />
      <PlTimelineItem title="Payment" bullet="2" />
      <PlTimelineItem title="Review" bullet="3" />
      <PlTimelineItem title="Done" bullet="4" />
    </PlTimeline>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 512,
      child: PlTimeline(
        orientation: PlassResponsive<PlassOrientation>(PlassOrientation.horizontal),
        active: 1,
        items: <PlTimelineItem>[
          PlTimelineItem(title: Text('Account'), bullet: Text('1')),
          PlTimelineItem(title: Text('Payment'), bullet: Text('2')),
          PlTimelineItem(title: Text('Review'), bullet: Text('3')),
          PlTimelineItem(title: Text('Done'), bullet: Text('4')),
        ],
      ),
    );
  }
}

size

React

import { PlTimeline, PlTimelineItem } from 'plass-ui';

export default function TimelineSizes() {
  return (
    <div className="flex w-full max-w-lg flex-wrap gap-8">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <PlTimeline key={size} size={size} density="compact" active={1}>
          <PlTimelineItem title={size} bullet="1" />
          <PlTimelineItem title="Next" bullet="2" />
        </PlTimeline>
      ))}
    </div>
  );
}

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

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

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 512,
      child: Wrap(
        spacing: 32,
        runSpacing: 32,
        children: <Widget>[
          for (final size in PlassSize.values)
            SizedBox(
              width: 200,
              child: PlTimeline(
                size: size,
                density: PlassDensity.compact,
                active: 1,
                items: <PlTimelineItem>[
                  PlTimelineItem(title: Text(size.name), bullet: const Text('1')),
                  const PlTimelineItem(title: Text('Next'), bullet: Text('2')),
                ],
              ),
            ),
        ],
      ),
    );
  }
}

Accessibility

• It is an <ol> for the reason it exists at all: the order is the content. A screen reader announcing "list of 5 items" over an unordered list would be describing something else.
• role="list" is written out because Tailwind's reset takes the markers off every <ol>, and Safari takes the list semantics off with them.
• The current step carries aria-current="step". That is the value for a sequence. "page" is a trail of documents and "true" is one of a set of options.
• The bullets and the connectors are aria-hidden. The status is in aria-current and in the text of each step, never in a shape alone.
• There is no Base UI primitive under this. A timeline has no selection, no roving focus and no keyboard contract, and using a composite primitive would hand a record of events the semantics of a widget.

• The steps are read in order, which is what the sequence is. Each is its own node.
• The bullets and the connectors are excluded from semantics. A bullet drawn as a number says nothing a screen reader needs that the step's own title does not.
• Which is the consequence worth knowing: status does not reach a screen reader here. Flutter's semantics tree has no current for a sequence, so a step that is complete and a step that is upcoming are announced the same way. Where the status matters, say it, in the step's meta, or in its body.
• A timeline has no selection, no roving focus and no keyboard contract, and it claims none.

Differences from the React build

React	Flutter	Why
<PlTimelineItem> children	items, as descriptions	Which step is complete is arithmetic on an index, and the last connector has to know it is the last. Neither can be asked of a Widget.
aria-current="step"	—	Flutter's semantics tree has no current. Say the status in the step's own text where it matters.
<ol> and role="list"	a grouped semantics node	There are no markers to reset and no list semantics for a reset to take away.
a border with dashed/dotted	a painted line	BorderSide has no dashes, so the runs are laid down by hand at the same weight.
render	—	Flutter has no polymorphic element.
children on a step	child	Flutter's name.