Timelines lay out a chronological list of events, such as an order history, activity feed, or changelog.
Order placed
We received your order and will begin processing it shortly.
Order shipped
Your package left the warehouse and is on its way.
Out for delivery
Your package is on the truck and should arrive today.
<wa-timelinelabel="Order history"><wa-timeline-item><wa-format-dateslot="opposite"date="2026-07-22T09:00:00"month="short"day="numeric"></wa-format-date><spanclass="wa-heading-m">Order placed</span><p>We received your order and will begin processing it shortly.</p></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="2026-07-23T09:00:00"month="short"day="numeric"></wa-format-date><spanclass="wa-heading-m">Order shipped</span><p>Your package left the warehouse and is on its way.</p></wa-timeline-item><wa-timeline-itemvariant="brand"><wa-format-dateslot="opposite"date="2026-07-24T09:00:00"month="short"day="numeric"></wa-format-date><spanclass="wa-heading-m">Out for delivery</span><p>Your package is on the truck and should arrive today.</p></wa-timeline-item></wa-timeline>
Showing progress through a process?
Use <wa-stepper> instead. A timeline is a record of what happened, with no current step.
Examples
Link to This Section
Opposite Content
Link to This Section
Add content to an item's opposite slot to show it on the other side of the rail from the main content, such as a date from <wa-format-date> or <wa-relative-time>.
Launch
Saturn V lifts off from Kennedy Space Center.
Translunar injection
The third stage fires again and Apollo 11 leaves Earth orbit.
Lunar landing
Eagle touches down in the Sea of Tranquility.
First step
One small step.
Splashdown
Columbia lands in the Pacific, southwest of Hawaii.
<wa-timeline><wa-timeline-item><wa-format-dateslot="opposite"date="1969-07-16T13:32:00Z"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><spanclass="wa-heading-m">Launch</span><p>Saturn V lifts off from Kennedy Space Center.</p></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="1969-07-16T16:22:00Z"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><spanclass="wa-heading-m">Translunar injection</span><p>The third stage fires again and Apollo 11 leaves Earth orbit.</p></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="1969-07-20T20:17:00Z"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><spanclass="wa-heading-m">Lunar landing</span><p>Eagle touches down in the Sea of Tranquility.</p></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="1969-07-21T02:56:00Z"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><spanclass="wa-heading-m">First step</span><p>One small step.</p></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="1969-07-24T16:50:00Z"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><spanclass="wa-heading-m">Splashdown</span><p>Columbia lands in the Pacific, southwest of Hawaii.</p></wa-timeline-item></wa-timeline>
Rendering on the server? Add the with-opposite attribute to each item that has opposite content.
The opposite column is shown once the item hydrates; with-opposite lays it out in the server-rendered markup. See Server-Side Rendering.
Custom Icon
Link to This Section
Use the icon slot on an item to show an element, such as <wa-icon> or an avatar, inside its marker. The icon takes the foreground color that matches the marker's variant. A marker with something in its icon slot is 2em instead of 1em. Resize it with --icon-marker-size, not --marker-size.
The call
A stranger arrives with a map and a warning.
The ordeal
The mountain is not as empty as promised.
The return
Home again, with a story nobody believes.
<wa-timeline><wa-timeline-itemvariant="warning"><wa-iconslot="icon"name="hat-wizard"></wa-icon><spanclass="wa-heading-m">The call</span><p>A stranger arrives with a map and a warning.</p></wa-timeline-item><wa-timeline-itemvariant="danger"><wa-iconslot="icon"name="dragon"></wa-icon><spanclass="wa-heading-m">The ordeal</span><p>The mountain is not as empty as promised.</p></wa-timeline-item><wa-timeline-itemvariant="success"><wa-iconslot="icon"name="crown"></wa-icon><spanclass="wa-heading-m">The return</span><p>Home again, with a story nobody believes.</p></wa-timeline-item></wa-timeline>
Rendering on the server? Add the with-icon attribute to each item with content in its icon slot.
The marker is sized up once the item hydrates; with-icon sizes it in the server-rendered markup. See Server-Side Rendering.
Variant
Link to This Section
Set the variant attribute on an item to color its marker with a semantic color. The default is neutral, whose marker stays quiet so the other variants stand out against it.
To flag something that failed or needs attention, pair the variant with an icon in the icon slot and state the reason in the content, so the meaning doesn't depend on color alone.
Build passedTests passedDeploy failed
Health check timed out after 30 seconds.
<wa-timeline><wa-timeline-itemvariant="success"><wa-iconslot="icon"name="check"></wa-icon><spanclass="wa-heading-m">Build passed</span></wa-timeline-item><wa-timeline-itemvariant="success"><wa-iconslot="icon"name="check"></wa-icon><spanclass="wa-heading-m">Tests passed</span></wa-timeline-item><wa-timeline-itemvariant="danger"><wa-iconslot="icon"name="xmark"></wa-icon><spanclass="wa-heading-m">Deploy failed</span><p>Health check timed out after 30 seconds.</p></wa-timeline-item></wa-timeline>
Size
Link to This Section
A timeline is sized relative to the current font size, like a badge. Set font-size on the timeline (or an ancestor element) to change it; markers and text scale together. The connector's thickness and the space between items come from the --connector-width and --gap custom properties, which don't follow the font size.
Extra SmallShippedSmallShippedMediumShippedLargeShippedExtra LargeShipped
To let a long timeline scroll sideways, wrap it in a <wa-scroller> and give the timeline a minimum width.
Sputnik 1
First artificial satellite.
Vostok 1
First human in orbit.
Apollo 11
First crewed lunar landing.
Columbia
First reusable orbiter flies.
Zarya
First ISS module.
<wa-scroller><wa-timelineclass="timeline-space-race"orientation="horizontal"><wa-timeline-item><wa-iconslot="icon"name="satellite-dish"></wa-icon><wa-format-dateslot="opposite"date="1957-10-04"year="numeric"></wa-format-date><spanclass="wa-heading-m">Sputnik 1</span><p>First artificial satellite.</p></wa-timeline-item><wa-timeline-item><wa-iconslot="icon"name="user-astronaut"></wa-icon><wa-format-dateslot="opposite"date="1961-04-12"year="numeric"></wa-format-date><spanclass="wa-heading-m">Vostok 1</span><p>First human in orbit.</p></wa-timeline-item><wa-timeline-item><wa-iconslot="icon"name="moon"></wa-icon><wa-format-dateslot="opposite"date="1969-07-20"year="numeric"></wa-format-date><spanclass="wa-heading-m">Apollo 11</span><p>First crewed lunar landing.</p></wa-timeline-item><wa-timeline-item><wa-iconslot="icon"name="shuttle-space"></wa-icon><wa-format-dateslot="opposite"date="1981-04-12"year="numeric"></wa-format-date><spanclass="wa-heading-m">Columbia</span><p>First reusable orbiter flies.</p></wa-timeline-item><wa-timeline-item><wa-iconslot="icon"name="satellite"></wa-icon><wa-format-dateslot="opposite"date="1998-11-20"year="numeric"></wa-format-date><spanclass="wa-heading-m">Zarya</span><p>First ISS module.</p></wa-timeline-item></wa-timeline></wa-scroller><style>.timeline-space-race{min-inline-size: 56rem;}</style>
Set the orientation attribute to auto to lay items out in a row and switch to a column when there's less than about 10em between items, so entries stay readable on small screens. Resize the example to see the switch. While laid out as a column, the timeline has the stacked custom state, so wa-timeline:state(stacked) targets it.
The default, vertical, stays a column at any width. auto measures the timeline in the browser, so a server-rendered auto timeline starts as a column and switches to a row once it hydrates.
Don't combine auto with <wa-scroller>. Pick sideways scrolling or switching to a column, not both.
Marker Placement
Link to This Section
The marker-placement attribute sets where each marker sits relative to its item's content. The default, start, puts the marker before the content; set it to end to put the marker after the content. Marker placement only applies while the timeline is laid out as a column, including an auto timeline that has switched to one.
Set it to alternate to switch sides item by item, so the rail runs down the middle, which suits a wide timeline. When the timeline is narrower than 30em, it lays every item out on the start side until it has room again.
ShippedBulk actions in the data grid
Select rows across pages and act on them all at once.
In progressReal-time collaboration
See where teammates are editing as they type.
PlannedOffline mode
Keep working on a flight; sync once you land.
<wa-timelinemarker-placement="alternate"><wa-timeline-itemvariant="success"><wa-badgeslot="opposite"appearance="outlined"variant="success"pill>Shipped</wa-badge><spanclass="wa-heading-m">Bulk actions in the data grid</span><p>Select rows across pages and act on them all at once.</p></wa-timeline-item><wa-timeline-itemvariant="brand"><wa-badgeslot="opposite"appearance="outlined"variant="brand"pill>In progress</wa-badge><spanclass="wa-heading-m">Real-time collaboration</span><p>See where teammates are editing as they type.</p></wa-timeline-item><wa-timeline-item><wa-badgeslot="opposite"appearance="outlined"pill>Planned</wa-badge><spanclass="wa-heading-m">Offline mode</span><p>Keep working on a flight; sync once you land.</p></wa-timeline-item></wa-timeline>
Marker Alignment
Link to This Section
By default, each marker sits at the top of its item, in line with the first line of text. Set the marker-alignment attribute to center to center the marker on the item's full height instead. Marker alignment only applies while the timeline is laid out as a column, including an auto timeline that has switched to one.
Base camp
Three days of acclimatizing, card games, and weather reports.
Summit push
Left at 2 AM by headlamp. Reached the top as the sun came up.
Descent
Knees complaining, spirits high. Back to the trailhead by dusk.
<wa-timelinemarker-alignment="center"><wa-timeline-itemvariant="success"><wa-iconslot="icon"name="campground"></wa-icon><wa-card><divslot="media"class="wa-frame:landscape"><imgsrc="https://images.unsplash.com/photo-1426604966848-d7adac402bff?auto=format&fit=crop&w=640&h=360&q=60"alt=""/></div><spanclass="wa-heading-m">Base camp</span><p>Three days of acclimatizing, card games, and weather reports.</p></wa-card></wa-timeline-item><wa-timeline-itemvariant="success"><wa-iconslot="icon"name="mountain"></wa-icon><wa-card><divslot="media"class="wa-frame:landscape"><imgsrc="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?auto=format&fit=crop&w=640&h=360&q=60"alt=""/></div><spanclass="wa-heading-m">Summit push</span><p>Left at 2 AM by headlamp. Reached the top as the sun came up.</p></wa-card></wa-timeline-item><wa-timeline-item><wa-iconslot="icon"name="person-hiking"></wa-icon><wa-card><divslot="media"class="wa-frame:landscape"><imgsrc="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?auto=format&fit=crop&w=640&h=360&q=60"alt=""/></div><spanclass="wa-heading-m">Descent</span><p>Knees complaining, spirits high. Back to the trailhead by dusk.</p></wa-card></wa-timeline-item></wa-timeline>
Providing Content
Link to This Section
An item's default slot accepts any content, so an entry can hold more than a title and a line of text.
Jamie Kim
opened the pull request
#2905
Adds the timeline component and its docs.
View Changes
Riley Park
requested changes
Changes requested
Can we add a test for an empty opposite slot before merging this?
Jamie Kim
pushed 2 commits
a1f3c9e Test the empty opposite slot
7b2d410 Tidy the docs examples
Riley Park
approved these changes
Approved
Looks great. The new tests are a nice touch.
Merged
into next
<wa-timelineclass="timeline-activity"><wa-timeline-item><wa-avatarslot="icon"initials="JK"label="Jamie Kim"></wa-avatar><wa-format-dateslot="opposite"date="2026-09-14T09:12:00"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><divclass="wa-stack wa-gap-xs"><divclass="wa-cluster wa-gap-2xs"><spanclass="wa-heading-m">Jamie Kim</span>
opened the pull request
<wa-badgeappearance="outlined"pill>#2905</wa-badge></div><p>Adds the timeline component and its docs.</p><divclass="wa-cluster"><wa-buttonsize="s"appearance="outlined">View Changes</wa-button></div></div></wa-timeline-item><wa-timeline-item><wa-avatarslot="icon"initials="RP"label="Riley Park"></wa-avatar><wa-format-dateslot="opposite"date="2026-09-14T11:03:00"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><divclass="wa-stack wa-gap-xs"><divclass="wa-cluster wa-gap-2xs"><spanclass="wa-heading-m">Riley Park</span>
requested changes
<wa-badgevariant="warning"appearance="outlined"pill>Changes requested</wa-badge></div><p>Can we add a test for an empty <code>opposite</code> slot before merging this?</p></div></wa-timeline-item><wa-timeline-item><wa-avatarslot="icon"initials="JK"label="Jamie Kim"></wa-avatar><wa-format-dateslot="opposite"date="2026-09-15T08:20:00"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><divclass="wa-stack wa-gap-xs"><divclass="wa-cluster wa-gap-2xs"><spanclass="wa-heading-m">Jamie Kim</span>
pushed 2 commits
</div><ulclass="wa-body-s"><li><code>a1f3c9e</code> Test the empty opposite slot</li><li><code>7b2d410</code> Tidy the docs examples</li></ul></div></wa-timeline-item><wa-timeline-item><wa-avatarslot="icon"initials="RP"label="Riley Park"></wa-avatar><wa-format-dateslot="opposite"date="2026-09-15T08:47:00"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><divclass="wa-stack wa-gap-xs"><divclass="wa-cluster wa-gap-2xs"><spanclass="wa-heading-m">Riley Park</span>
approved these changes
<wa-badgevariant="success"appearance="outlined"pill>Approved</wa-badge></div><p>Looks great. The new tests are a nice touch.</p></div></wa-timeline-item><wa-timeline-itemvariant="brand"><wa-iconslot="icon"name="code-merge"></wa-icon><wa-format-dateslot="opposite"date="2026-09-15T09:02:00"month="short"day="numeric"hour="numeric"minute="numeric"></wa-format-date><divclass="wa-cluster wa-gap-2xs"><spanclass="wa-heading-m">Merged</span>
into <code>next</code></div></wa-timeline-item></wa-timeline><style>.timeline-activity{--icon-marker-size: 2.5em;}.timeline-activity ul{margin: 0;padding-inline-start: 1.25em;}</style>
Grouping Entries
Link to This Section
To group entries under headings, such as by day, give each group its own heading and its own timeline. Keep the headings outside the timelines, since a timeline should only hold items. Set the label attribute on each timeline so screen reader users can tell the groups apart.
Today
Payment received
Paid in full by bank transfer.
Reminder sent
A second notice went to the billing contact.
Yesterday
Invoice sent
Due in 30 days.
Quote approved
The client signed off on the estimate.
<divclass="wa-stack"><h4>Today</h4><wa-timelinelabel="Today"><wa-timeline-itemvariant="success"><spanclass="wa-heading-m">Payment received</span><p>Paid in full by bank transfer.</p></wa-timeline-item><wa-timeline-item><spanclass="wa-heading-m">Reminder sent</span><p>A second notice went to the billing contact.</p></wa-timeline-item></wa-timeline><h4>Yesterday</h4><wa-timelinelabel="Yesterday"><wa-timeline-item><spanclass="wa-heading-m">Invoice sent</span><p>Due in 30 days.</p></wa-timeline-item><wa-timeline-item><spanclass="wa-heading-m">Quote approved</span><p>The client signed off on the estimate.</p></wa-timeline-item></wa-timeline></div>
Adding Entries
Link to This Section
Append a <wa-timeline-item> to add an entry at the end. To show the newest entry at the top, put it first in the markup and add entries with prepend(). Reading and focus order follow document order, so they match the screen.
1–0Goal, Rovers
A low cross from the left, tapped in at the far post.
0–0Kickoff
Rovers get us under way, playing left to right.
Add Play
<divclass="wa-stack"><wa-timelineid="timeline-newest"><wa-timeline-itemvariant="success"><wa-badgeslot="opposite"appearance="outlined"pill>1–0</wa-badge><spanclass="wa-heading-m">Goal, Rovers</span><p>A low cross from the left, tapped in at the far post.</p></wa-timeline-item><wa-timeline-item><wa-badgeslot="opposite"appearance="outlined"pill>0–0</wa-badge><spanclass="wa-heading-m">Kickoff</span><p>Rovers get us under way, playing left to right.</p></wa-timeline-item></wa-timeline><wa-divider></wa-divider><wa-buttonid="timeline-newest-advance"appearance="filled">Add Play</wa-button></div><script>const timelineNewest = document.getElementById('timeline-newest');const timelineNewestButton = document.getElementById('timeline-newest-advance');const timelineNewestPlays =[{score:'1–0',variant:'warning',label:'Yellow card',body:'A late tackle in midfield. The referee has a word.',},{score:'1–1',variant:'brand',label:'Goal, City',body:'A free kick curled over the wall and into the corner.',},{score:'1–1',variant:'neutral',label:'Full time',body:'Honors even. Both sides will take the point.'},];
timelineNewestButton.addEventListener('click',()=>{const next = timelineNewestPlays.shift();if(!next)return;const item = document.createElement('wa-timeline-item');
item.variant = next.variant;
item.innerHTML =`<wa-badge slot="opposite" appearance="outlined" pill>${next.score}</wa-badge><span class="wa-heading-m">${next.label}</span><p>${next.body}</p>`;
timelineNewest.prepend(item);if(timelineNewestPlays.length ===0) timelineNewestButton.disabled =true;});</script>
With marker-placement="alternate", use append instead of prepend.
Sides are assigned in document order, so prepending an entry moves existing entries to the other side.
Customizing
Link to This Section
Use the exported CSS parts and custom properties to restyle the timeline. Most parts, such as marker and connector, belong to <wa-timeline-item>, so the selector targets the items, not the timeline; see the Timeline Item page for every part an item exposes. Each item can also set the --marker-size, --icon-marker-size, and --connector-gap custom properties for itself.
This example sets the timeline's --gap, --marker-size, and --connector-width custom properties, and the first entry sets a larger --marker-size for itself.
Adopted
Eight weeks old and already in charge.
First vet visit
A clean bill of health.
Learned the word "dinner"
Responds to it from three rooms away.
Claimed the window sill
The sunny end is hers now. Negotiations are closed.
Turned one
Celebrated with a new basket and two friends.
<wa-timelineclass="timeline-mittens"marker-placement="alternate"><wa-timeline-itemstyle="--marker-size: 1.5em;"><wa-format-dateslot="opposite"date="2025-06-14"month="long"year="numeric"></wa-format-date><divclass="wa-flank:end wa-gap-s"><div><spanclass="wa-heading-m">Adopted</span><p>Eight weeks old and already in charge.</p></div><divclass="wa-frame wa-border-radius-m"><imgsrc="https://images.unsplash.com/photo-1547191783-94d5f8f6d8b1?auto=format&fit=crop&w=160&h=160&q=60"alt=""/></div></div></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="2025-07-02"month="long"year="numeric"></wa-format-date><divclass="wa-flank wa-gap-s"><divclass="wa-frame wa-border-radius-m"><imgsrc="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?auto=format&fit=crop&w=160&h=160&q=60"alt=""/></div><div><spanclass="wa-heading-m">First vet visit</span><p>A clean bill of health.</p></div></div></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="2025-09-08"month="long"year="numeric"></wa-format-date><divclass="wa-flank:end wa-gap-s"><div><spanclass="wa-heading-m">Learned the word "dinner"</span><p>Responds to it from three rooms away.</p></div><divclass="wa-frame wa-border-radius-m"><imgsrc="https://images.unsplash.com/photo-1591871937573-74dbba515c4c?auto=format&fit=crop&w=160&h=160&q=60"alt=""/></div></div></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="2025-11-19"month="long"year="numeric"></wa-format-date><divclass="wa-flank wa-gap-s"><divclass="wa-frame wa-border-radius-m"><imgsrc="https://images.unsplash.com/photo-1559209172-0ff8f6d49ff7?auto=format&fit=crop&w=160&h=160&q=60"alt=""/></div><div><spanclass="wa-heading-m">Claimed the window sill</span><p>The sunny end is hers now. Negotiations are closed.</p></div></div></wa-timeline-item><wa-timeline-item><wa-format-dateslot="opposite"date="2026-06-14"month="long"year="numeric"></wa-format-date><divclass="wa-flank:end wa-gap-s"><div><spanclass="wa-heading-m">Turned one</span><p>Celebrated with a new basket and two friends.</p></div><divclass="wa-frame wa-border-radius-m"><imgsrc="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?auto=format&fit=crop&w=160&h=160&q=60"alt=""/></div></div></wa-timeline-item></wa-timeline><style>.timeline-mittens{--gap:var(--wa-space-2xl);--marker-size: 0.75em;--connector-width: 0.15em;}.timeline-mittens .wa-frame{inline-size: 4rem;flex: none;}</style>
Here the connector and markers become one rule with diamond stops: the --connector-gap custom property is set to 0px so the line runs straight into each marker, and the marker part is rotated into a diamond. The latest release takes the brand variant so it stands out, and version numbers sit in the opposite slot as <wa-badge>s.
v3.14Added the stepper component
Guides users through a process one step at a time.
v3.15Added the lightbox component
Shows images and videos in a full-screen viewer that opens from their thumbnails.
v3.16Added the timeline component
Lays out a chronological list of events, like this one.
<wa-timelineclass="release-timeline"><wa-timeline-item><wa-badgeslot="opposite"appearance="outlined"pill>v3.14</wa-badge><spanclass="wa-heading-m">Added the stepper component</span><p>Guides users through a process one step at a time.</p></wa-timeline-item><wa-timeline-item><wa-badgeslot="opposite"appearance="outlined"pill>v3.15</wa-badge><spanclass="wa-heading-m">Added the lightbox component</span><p>Shows images and videos in a full-screen viewer that opens from their thumbnails.</p></wa-timeline-item><wa-timeline-itemvariant="brand"><wa-badgeslot="opposite"appearance="outlined"variant="brand"pill>v3.16</wa-badge><spanclass="wa-heading-m">Added the timeline component</span><p>Lays out a chronological list of events, like this one.</p></wa-timeline-item></wa-timeline><style>.release-timeline{--marker-size: 0.875em;--connector-gap: 0px;--connector-color:var(--wa-color-neutral-fill-quiet);}.release-timeline wa-timeline-item::part(marker){rotate: 45deg;border-radius:var(--wa-border-radius-s);background-color:var(--wa-color-neutral-fill-loud);}.release-timeline wa-timeline-item[variant='brand']::part(marker){background-color:var(--wa-color-brand-fill-loud);}</style>
Accessibility Considerations
Link to This Section
Structure. The timeline renders an ordered list, and each <wa-timeline-item> carries role="listitem". Set the label attribute whenever more than one timeline appears on the same page, so screen reader users can tell them apart.
Keyboard. Nothing in the timeline takes focus. Items are records, not controls, so the timeline never intercepts clicks or adds keyboard handling. If an entry needs to link somewhere or trigger an action, put a real <a> or <wa-button> in its content.
Added entries aren't announced. Adding a <wa-timeline-item> updates the list silently; there's no live region. If an update needs to be announced, do it from your own live region rather than relying on the timeline.
Color and meaning. The variant attribute is cosmetic. It changes color, which doesn't carry meaning on its own, so state the reason in the item's visible content rather than relying on color alone.
Custom icons. When the icon slot holds an icon that's the only indicator of an item's meaning (e.g. a checkmark for "completed" with no other label), give it an accessible name with <wa-icon label="...">. A marker that only repeats what the item's own content already says can stay decorative.
API
Link to This Section
Importing
Link to This Section
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To
cherry-pick a component manually, use one of the following snippets.
A label that describes the timeline to assistive devices. Especially useful when more than one is on the page.
Typestring
Default''
markerAlignment
marker-alignment
Where the marker sits along its item. start lines it up with the first line of text. center centers it on the
item's full height and runs the connector behind it as one line, which suits cards. Only applies while the
timeline is laid out as a column.
Type'start' | 'center'
Default'start'
markerPlacement
marker-placement
Which side of each item's content the marker sits on. start puts the marker before the content and end puts
it after. alternate switches sides on every other item, so the rail runs down the middle. An alternating timeline
narrower than 30em lays every item out like start until it has room. Only applies while the timeline is laid out
as a column.
Type'start' | 'end' | 'alternate'
Default'start'
orientation
orientation
The timeline's layout direction. auto lays the items out in a row when there's room and in a column when the
timeline is too narrow. It measures in the browser, so a server-rendered auto timeline starts as a column.
vertical stays the default.
The gap between a marker's edge and the connector line. Use a length such as 0px, not a bare 0, to remove it.
Default0.35em
--connector-width
The thickness of the connector line, in either orientation.
Defaultvar(--wa-border-width-m)
--gap
The space between items. Connectors are sized from this value, so set it here instead of setting gap on the timeline part. Use a length such as 0px, not a bare 0, to remove it.
Defaultvar(--wa-space-l)
--icon-marker-size
The size of a marker whose item has content in its icon slot, such as an icon or avatar. Usually set here so every item matches.
Default2em
--marker-size
The size of a marker with no icon. Usually set here so every item matches.
During SSR, <wa-timeline> can't reach its items, so each item renders with the default start placement and start alignment until it hydrates. The list itself follows orientation and marker-placement right away, so a horizontal or alternating timeline doesn't lay out correctly until then. A server-rendered alternating timeline also starts out alternating and only stacks after it hydrates, if it's too narrow. A server-rendered auto timeline is a column until it hydrates and measures its width.