--- title: "Timeline" description: "A list of events in chronological order along a line: dots, icons or avatars, colours and sizes, vertical or horizontal, on one side or alternating." url: "https://susonwaiba.github.io/htmx-ui/docs/components/timeline" section: "Components" --- # Timeline A list of events in chronological order along a line: dots, icons or avatars, colours and sizes, vertical or horizontal, on one side or alternating. ```html

7 October 2026
Version 1.0 released

Stable APIs for every component, the engine and the plugins.
14 August 2026
Release candidate

Feature freeze, and a public call for testing.
2 May 2026
First public beta

Forty components and the docs site.

``` ## Markup - An `

`: a list in order, which is what screen readers announce. It is CSS only, with no behaviour. - Each item has a `.timeline-marker` and a `.timeline-content`. Inside the content, `.timeline-time` (a `
`), `.timeline-title` and `.timeline-description` are all optional; any other markup works too. - The line to the next item is drawn for you, and stops at the last item. - Newest first or oldest first is up to you: the timeline shows items in the order they are written. ## Markers An empty `.timeline-marker` is a dot. `.timeline-marker-primary`, `-success`, `-warning`, `-danger` and `-info` colour it, and `.timeline-marker-outline` makes it hollow. ```html
1. Default
2. Primary
3. Success
4. Warning
5. Danger
6. Info
1. Default
2. Primary
3. Success
4. Warning
5. Danger
6. Info
``` Put an icon, a number or an image in the marker and it becomes a circle; the line and the first line of text centre on it. Plain circles have a border; the colours fill them, and `.timeline-marker-outline` draws a coloured ring instead. ```html
1. Pull request merged
  
  feat(ui): timeline component
2. 3 commits pushed
  
  Alternating layout, sizes and docs.
3. Review requested from Sam
  Yesterday at 4:20 pm
4. Comment
  
  "Looks good: could the dots line up with the first line of text?"
``` ## Progress and the current step For a process (an order, a deployment, an application), colour the steps that are done, mark the current item with `aria-current="step"`, which adds a ring and tells screen readers where it is, and leave the rest as outline markers. Numbers work as markers too. ```html
1. Order placed
  3 Oct, 9:12 am
2. Packed
  4 Oct, 2:40 pm
3. Out for delivery
  
  Arriving today between 1 and 3 pm.
4. Delivered
1. 1
  Create an account
  Done
2. 2
  Verify your email
  Check your inbox
3. 3
  Invite your team
``` ## Rich content The content takes any markup: a [card](https://susonwaiba.github.io/htmx-ui/docs/components/card), an [alert](https://susonwaiba.github.io/htmx-ui/docs/components/alert), buttons. ```html
1. Deploy failed
  10:05 am
  
  Build step exited with code 1
  
  Cannot find module "htmx-ui/timeline". View logs
2. Deploy started
  10:03 am
  
  main · 02e12f4
  
  docs: 0.2.0 changelog and contributor guides
``` ## Opposite content A `.timeline-opposite` in every item goes on the other side of the line, right-aligned in a column `--timeline-opposite` wide (6rem): dates, times or amounts that read down one edge. ```html
1. Keynote
  Main hall
  9:00 am
2. Building with htmx 4
  Room 2
  10:30 am
3. Lunch
  12:00 pm
``` ## Alternating `.timeline-alternate` puts the line in the middle and the items on either side of it in turn, with the `.timeline-opposite`, if any, across from each one. On narrow screens (below the `sm` breakpoint) it falls back to one side, so nothing gets squeezed. ```html
1. Idea
  
  A component library for htmx with no React and no build step for users.
  
  November 2025
2. First components
  
  Buttons, inputs, dialogs and tabs, styled with Tailwind v4.
  
  January 2026
3. Docs site
  
  Built with its own engine, with search and versioned docs.
  
  April 2026
4. Version 1.0
  
  Stable, with a scaffolder for bun, npm, pnpm and yarn.
  
  October 2026
``` ## Horizontal `.timeline-horizontal` lays the items out in a row, each at least `--timeline-min` (10rem) wide, scrolling sideways when they don't fit. A `.timeline-opposite` goes above the line. ```html
1. Plan
  Scope and estimates
  Week 1
2. Design
  Mockups signed off
  Week 2
3. Build
  In progress
  Weeks 3–5
4. Launch
  Week 6
``` With `.timeline-alternate`, horizontal items go above and below the line in turn. The markers stay in one row whatever sits above them. ```html
1. Jan
  Kick-off
2. Mar
  Alpha
  Internal testing
3. May
  Beta
4. Aug
  Release candidate
  Feature freeze
5. Oct
  1.0
``` ## Line style `.timeline-dashed` and `.timeline-dotted` change the line, vertical or horizontal. ```html
1. Dashed
2. Second
3. Third
1. Dotted
2. Second
3. Third
``` ## Sizes `.timeline-sm` and `.timeline-lg` scale the markers, the text and the spacing together. ```html
1. Small
  Signed up
2. Email sent
  Welcome
3. Profile
  Completed
1. Default
  Signed up
2. Email sent
  Welcome
3. Profile
  Completed
1. Large
  Signed up
2. Email sent
  Welcome
3. Profile
  Completed
``` ## With htmx A timeline is a list, so loading more events is appending items. Here a button at the end fetches the next page and replaces itself with it (`hx-swap="outerHTML"`), the response being more `
`s and a new button: ```html activity.html
1. …
``` ## Customising Every measurement is a custom property on `.timeline`; set them with Tailwind's arbitrary properties or your own CSS. | Property | Description | | --- | --- | | `--timeline-dot` | Dot size (0.75rem). | | `--timeline-icon` | Circle size for icon, text and image markers (2rem). | | `--timeline-line` | Line thickness (2px). | | `--timeline-gap` | Between the marker and the content (0.75rem). | | `--timeline-space` | Between items (1.5rem). | | `--timeline-opposite` | Width of the .timeline-opposite column, vertical (6rem). | | `--timeline-min` | Narrowest item, horizontal (10rem). | ## Reference | Class / attribute | Description | | --- | --- | | `.timeline` | The list: an
1. . aria-current="step" rings its marker. | | `.timeline-marker` | Empty: a dot. With an icon, text or image: a circle. | | `.timeline-marker-primary / -success / -warning / -danger / -info` | Marker colours. | | `.timeline-marker-outline` | A hollow marker, in its colour. | | `.timeline-content` | The event: .timeline-time, .timeline-title, .timeline-description, or anything. | | `.timeline-opposite` | Across the line from the content. | | `.timeline-alternate` | Items on both sides of the line in turn. | | `.timeline-horizontal` | Items in a row. | | `.timeline-dashed / .timeline-dotted` | Line style. | | `.timeline-sm / .timeline-lg` | Sizes. |

Version 1.0 released

Release candidate

First public beta

Pull request merged

3 commits pushed

Review requested from Sam

Comment

Order placed

Packed

Out for delivery

Delivered

Create an account

Verify your email

Invite your team

Deploy failed

Deploy started

Keynote

Building with htmx 4

Lunch

Idea

First components

Docs site

Version 1.0

Plan

Design

Build

Launch

Kick-off

Alpha

Beta

Release candidate

1.0

Small

Email sent

Profile

Default

Email sent

Profile

Large

Email sent

Profile