Blog

Responsive Vertical Timeline with HTML and CSS

Responsive vertical timeline with alternating desktop cards and a single-column mobile layout

Responsive Vertical Timeline with HTML and CSS

To build a responsive vertical timeline, put events in a chronological ordered list, draw the line and dots with CSS pseudo-elements, and place event cards on alternating sides only when the component has enough room. Keep a single-column layout as the default so dates and descriptions stay readable on smaller screens.

This tutorial creates a pure HTML and CSS timeline with semantic dates, native expandable notes and a layout based on the component’s width. It needs no JavaScript, icon library or external font.

Try the responsive timeline live demo

Responsive timeline playground

A fictional project journey, shown in chronological order. Open any milestone notes, or choose a single-column layout to compare the designs.

  1. Discover

    Define the project goals and the people the site needs to serve.

    Discovery notes

    Write a short brief, list the key pages and agree on what a useful first release should include.

  2. Design

    Turn the content plan into a small set of responsive layouts.

    Design notes

    Review readable type, navigation, focus indicators and how longer content behaves in the smallest layout.

  3. Build

    Create reusable components and connect the approved content.

    Build notes

    Keep meaningful HTML in source order. Check long headings, keyboard interaction and image dimensions.

  4. Launch

    Review the finished pages and prepare the first release.

    Launch notes

    Check links and forms, review metadata, and document how future content updates will be made.

The layout follows this component’s available width. At 640px of content width it alternates sides; below that it keeps the rail on the left. No JavaScript or animation is used.

When should you use a vertical timeline?

A vertical timeline presents events whose order matters: project milestones, release history, education or a short company history. Each entry should identify when something happened and what changed. Use a normal list or table when chronology is not the main relationship, or when readers need to compare many attributes at once.

The example uses a fictional project journey with four dates. Replace these sample milestones with accurate information before using it on a real site.

1. Write the events in chronological HTML order

An ordered list provides the sequence. Each event includes a date, a descriptive heading, a short explanation and optional notes. Keep the source order identical to the order in which you want people to read and navigate the events.

<ol class="swctl-items" role="list">
  <li class="swctl-item">
    <div class="swctl-card">
      <time datetime="2025-02-03">3 February 2025</time>
      <h4>Discover</h4>
      <p>Define the project goals and the people the site needs to serve.</p>
      <details>
        <summary>Discovery notes</summary>
        <p>Write a brief and agree on the first release.</p>
      </details>
    </div>
  </li>
  <!-- Add the next event here in chronological order. -->
</ol>

The datetime attribute supplies a machine-readable date while the text gives readers an unambiguous label. See MDN’s time element reference for valid values. The demo keeps role="list" on the ordered list to preserve its intended list semantics in browser and assistive-technology combinations where removing visible list markers can affect the announcement.

2. Create the single-column timeline first

Give the list a positioning context. Its empty pseudo-element becomes the decorative rail, while each event’s pseudo-element becomes a dot. Indent the cards to leave room for the rail. The line belongs to this list, so it does not remain fixed across the entire page.

.swctl-items {
  position: relative;
  list-style: none;
  margin: 26px 0 16px;
  padding: 0;
}
.swctl-items::before {
  content: "";
  position: absolute;
  left: 11px;
  top: 24px;
  bottom: 24px;
  width: 3px;
  transform: translateX(-50%);
  background: #9cb6e4;
}
.swctl-item { position: relative; margin-bottom: 22px; }
.swctl-item::before {
  content: "";
  position: absolute;
  left: 11px;
  top: 26px;
  width: 16px;
  height: 16px;
  box-sizing: border-box;
  border: 4px solid #eef4ff;
  border-radius: 50%;
  background: #2455d9;
  transform: translateX(-50%);
}
.swctl-card {
  margin-left: 40px;
  padding: 20px 22px;
  border: 1px solid #cbd9ef;
  border-radius: 12px;
  background: white;
  overflow-wrap: anywhere;
}

The dots and rail convey decoration, not the date or event meaning. Dates and headings remain ordinary text. Do not put essential labels inside CSS content or rely on color alone to describe event status.

3. Alternate cards when the component has enough width

A viewport can be wide while a timeline sits inside a narrow sidebar. A container query lets this component respond to its own available space. Declare an inline-size query container on the wrapper, then switch the cards at 640px of container content width.

.swctl { container: swctl / inline-size; }
@container swctl (min-width: 640px) {
  .swctl-items::before { left: 50%; }
  .swctl-item::before { left: 50%; }
  .swctl-card {
    width: calc(50% - 34px);
    margin-left: 0;
  }
  .swctl-item:nth-child(even) .swctl-card {
    margin-left: auto;
  }
}

Odd cards stay on the left and even cards move to the right. Each list item still occupies its own row in normal flow. Expanding a note increases that row’s height and pushes later events down. There are no negative margins that make cards overlap and no visual reordering that conflicts with chronology.

Read MDN’s container queries guide for the query-container model. If a browser ignores container queries, the default single-column layout remains usable. Adjust the breakpoint based on your actual card content rather than a device label.

4. Add optional notes with details and summary

The native details element supplies a disclosure without a custom click handler. Its summary is the interactive label. In the demo, keyboard users can Tab to each summary and toggle the notes with Enter or Space.

<details>
  <summary>Design notes</summary>
  <p>Review readable type, navigation and narrow-screen layouts.</p>
</details>

<style>
.swctl summary { cursor: pointer; font-weight: 700; }
.swctl summary:focus-visible {
  outline: 3px solid #7346b8;
  outline-offset: 4px;
}
</style>

Keep the date, heading and main description outside the disclosure so the event is understandable before opening it. The details reference explains its native open state and summary behavior. Do not add custom button roles or extra tab stops to static cards.

5. Let readers compare the single-column layout

The playground adds an optional checkbox that forces the single column at any width. It uses :has() to connect the checked input to the timeline’s layout. The control is hidden in browsers without selector support; automatic responsive layout remains independent of this optional feature.

<label class="swctl-control">
  <input type="checkbox" class="swctl-single"> Use single-column layout
</label>

<style>
.swctl-control { display: none; }
@supports selector(:has(*)) { .swctl-control { display: flex; } }
.swctl:has(.swctl-single:checked) .swctl-items::before,
.swctl:has(.swctl-single:checked) .swctl-item::before { left: 11px; }
.swctl:has(.swctl-single:checked) .swctl-card {
  width: auto;
  margin-left: 40px;
}
</style>

This is a layout preference for the current page, not a filter. Every event remains present. The demo has no animation, so it adds no motion for users with reduced-motion preferences.

Download and customize the timeline

  1. Extract the ZIP and open index.html in a current browser.
  2. Replace the sample dates, headings and descriptions with your own events.
  3. Add a new list item in the correct chronological position. Set its datetime value accurately.
  4. Edit the rail, dot and card colors in style.css.
  5. Test a long heading, an expanded note and the narrowest container you support.

The complete project contains HTML, CSS and a README. It works offline and needs no build tools, scripts or remote assets. When embedding it in WordPress, retain the scoped classes and review theme styles that affect lists, headings and disclosures.

Common timeline layout problems

  • The rail covers unrelated content: position it absolutely inside the timeline list, rather than fixing it to the document body.
  • Cards overlap when notes expand: remove fixed heights and negative margins. Keep each event in normal flow.
  • The desktop layout appears in a narrow column: use the component’s container width to decide when cards alternate.
  • Long content overflows: allow text to wrap and avoid fixed card widths. Test long words and URLs.
  • Reading order feels confusing: keep the HTML in date order and avoid CSS order or separate left/right event lists.
  • The checkbox has no effect: verify selector support and confirm it is inside the same wrapper as the list.

Frequently asked questions

Does a responsive timeline need JavaScript?

No. CSS handles the layout, native details elements handle expandable notes, and the optional checkbox uses CSS selector state.

Why use an ordered list?

The sequence is part of the content. A single list keeps every event in a clear chronological source order regardless of card placement.

Can I show newest events first?

Yes. Put the events in newest-first order in the HTML and make that direction clear to readers. Do not reverse only the visual layout.

Will the timeline work inside a sidebar?

Yes. It starts as a single column and uses a container query for the alternating layout. A narrow sidebar therefore keeps the compact version even on a wide screen.

Can I add more events or longer descriptions?

Yes. Add list items in the intended sequence. The cards grow with their content; test readability and page length with your real data.

More HTML and CSS practice

Try the animated gradient background for a decorative background with pause controls, or explore responsive sliding tabs for grouping related topics into panels.

Conclusion

A useful timeline starts with accurate dates and a clear sequence. Add the rail and alternating cards as presentation, keep narrow layouts readable, and let content expand without disturbing the event order.