# SvTimeline
A vertical activity or history feed: a connecting rail with a colored marker per
entry, plus a title, timestamp, and description.
`SvTimeline` is data-driven - pass an array of `items` and it renders the rail,
markers, and text. Each marker can carry its own color and glyph, and an
optional `item` snippet lets you replace the default row with custom content for
richer feeds. Colors default to the grid accent and read from `--sg-*` tokens.
Related: [SvChip](https://svgrid.com/docs/help/ui-components/sv-chip/) · [SvAvatar](https://svgrid.com/docs/help/ui-components/sv-avatar/) · [Feedback & display overview](https://svgrid.com/docs/help/ui-components/feedback/)
## Installation
Add it with the CLI - this drops a ready-to-edit `SvTimeline` starter into your app:
Prefer to see it first? `npx @svgrid/ui try timeline` opens it in a throwaway sandbox - no project needed.
Or install the package and import it directly. `SvTimeline` ships free in
`@svgrid/grid` (dependency-free):
```ts
import { SvTimeline } from '@svgrid/grid'
```
## Example
> Live demo: Status & display: alert, stat, timeline, chip, divider, empty - https://svgrid.com/demos/339-status-display/
```svelte
```
## Props
| Prop | Type | Default | Description |
| ------- | ----------------------------- | ------- | ------------------------------------------------------------- |
| `items` | `ReadonlyArray` | - | The entries to render, top to bottom. |
| `item` | `Snippet<[TimelineItem]>` | - | Custom content per entry; receives the item. |
### The `TimelineItem` type
```ts
type TimelineItem = {
id?: string | number // stable key; falls back to the array index
title: string // required headline
description?: string // secondary line under the title
time?: string // right-aligned timestamp / label
color?: string // marker color (any CSS color); defaults to the accent
icon?: string // optional glyph inside the marker (emoji / char)
}
```
## Examples
### Colored status markers
Give each entry a `color` and `icon` to encode its state at a glance:
```svelte
```
### Custom entry content
The `item` snippet takes over the row, so you can drop in avatars, chips, or
links while the rail and marker stay consistent:
```svelte
{#snippet item(entry)}
{entry.title}{entry.time}
{/snippet}
```
### Mapping records to items
Build `items` from your data before passing it in:
```svelte
{#await history then events}
({
id: e.id, title: e.action, time: e.at, description: e.note,
}))} />
{/await}
```
### Activity feed with actors
Type the feed with `TimelineItem` and use the `item` snippet to add the actor's
avatar beside each event while the rail and markers stay consistent:
```svelte
{#snippet item(entry)}
{entry.title}{entry.time}
{#if entry.description}
{entry.description}
{/if}
{/snippet}
```
> Tip: the `color` on each item sets the marker tint and its soft ring, so a
> single hue per event type (blue for opened, green for passed, amber for
> waiting) makes the feed scannable without any legend.
## Accessibility
- The feed renders as an ordered list (`` / `
`), so its sequence is
conveyed to assistive tech.
- Markers and glyphs are decorative; the `title`, `time`, and `description` text
carries the meaning.
- Provide a stable `id` per item for correct keying when the feed updates.
## See also
- [Feedback overview](https://svgrid.com/docs/help/ui-components/feedback/) - the whole status and display layer at a glance.
- [SvChip](https://svgrid.com/docs/help/ui-components/sv-chip/) - inline tokens for timeline entries.
- [SvAvatar](https://svgrid.com/docs/help/ui-components/sv-avatar/) - actor avatars inside custom entry rows.
---
SvGrid is the Svelte 5 data grid (`npm install @svgrid/grid`, MIT). This page: https://svgrid.com/docs/help/ui-components/sv-timeline/ . All docs: https://svgrid.com/llms.txt