Timeline

<loomi-timeline-item> entries grouped in <loomi-timeline> — display events in chronological order, like an activity feed.

1
npm install @loomidev/timeline lit

1
import "@loomidev/timeline";

Basic Usage

1
<loomi-timeline>
2
  <loomi-timeline-item date="10 days ago" content="You signed up"></loomi-timeline-item>
3
  <loomi-timeline-item date="8 days ago" content="Customer rep assigned"></loomi-timeline-item>
4
  <loomi-timeline-item date="8 days ago" content="Customer rep called"></loomi-timeline-item>
5
  <loomi-timeline-item content="Account is being reviewed"></loomi-timeline-item>
6
  <loomi-timeline-item content="Account activated"></loomi-timeline-item>
7
</loomi-timeline>

The trailing connector line is removed from the last item automatically — there’s nothing to set.

Rich Content

content only takes plain text. For HTML — bold text, links, code, etc. — put it in the default slot instead; it overrides the content attribute.

You signed up with email user@example.com

1
<loomi-timeline>
2
  <loomi-timeline-item date="10 days ago">
3
    <strong>You signed up</strong> with email <code>user@example.com</code>
4
  </loomi-timeline-item>
5
</loomi-timeline>

Bigger Anchors

1
<loomi-timeline anchor="big">
2
  <loomi-timeline-item date="10 days ago" content="You signed up"></loomi-timeline-item>
3
</loomi-timeline>

Completed State

Filled circles mark a step as done; on a big anchor, a checkmark appears too.

1
<loomi-timeline anchor="big">
2
  <loomi-timeline-item completed date="10 days ago" content="You signed up"></loomi-timeline-item>
3
  <loomi-timeline-item completed date="8 days ago" content="Customer rep assigned"></loomi-timeline-item>
4
  <loomi-timeline-item content="Account is being reviewed"></loomi-timeline-item>
5
</loomi-timeline>

Stacked Timelines

stacked on the <loomi-timeline> wrapper puts dates above content instead of beside it, and is shared by every child item.

1
<loomi-timeline stacked>
2
  <loomi-timeline-item date="just now" content="Database server restarted"></loomi-timeline-item>
3
  <loomi-timeline-item date="30 minutes ago" content="2 endpoints are failing — check the logs"></loomi-timeline-item>
4
  <loomi-timeline-item date="Yesterday" content="Data recovery completed with 2 errors"></loomi-timeline-item>
5
</loomi-timeline>

completed on the wrapper marks every item as done at once — override a single item by setting completed="false" directly on it.

1
<loomi-timeline stacked completed anchor="big">
2
  <loomi-timeline-item date="just now" content="Database server restarted"></loomi-timeline-item>
3
  <loomi-timeline-item date="Yesterday" content="Data recovery" completed="false"></loomi-timeline-item>
4
</loomi-timeline>

Anchor Icons and Avatars

Icons and avatars only render when anchor="big".

1
<loomi-timeline anchor="big" completed>
2
  <loomi-timeline-item date="10 days ago" content="You signed up" icon="bell-alert"></loomi-timeline-item>
3
  <loomi-timeline-item date="8 days ago" content="Customer rep assigned" icon="bolt"></loomi-timeline-item>
4
  <loomi-timeline-item content="Account is being reviewed" icon="key" completed="false"></loomi-timeline-item>
5
</loomi-timeline>
6

7
<loomi-timeline anchor="big">
8
  <loomi-timeline-item date="10 days ago" content="You signed up" avatar="/avatars/ada.jpg"></loomi-timeline-item>
9
  <loomi-timeline-item date="8 days ago" content="Customer rep assigned" avatar="/avatars/rep.jpg"></loomi-timeline-item>
10
</loomi-timeline>

Placement

Set placement on the <loomi-timeline> wrapper — it’s shared by every child item. Default is left (anchor on the left, content to its right).

1
<loomi-timeline placement="left" anchor="big">
2
  <loomi-timeline-item date="10 days ago" content="You signed up"></loomi-timeline-item>
3
  <loomi-timeline-item date="8 days ago" content="Customer rep assigned"></loomi-timeline-item>
4
</loomi-timeline>

right mirrors the whole layout — content on the left, anchor on the right:

1
<loomi-timeline placement="right" anchor="big">
2
  <loomi-timeline-item date="10 days ago" content="You signed up"></loomi-timeline-item>
3
  <loomi-timeline-item date="8 days ago" content="Customer rep assigned"></loomi-timeline-item>
4
</loomi-timeline>

alternate centers a single spine and alternates each item to its left and right — which side an item lands on is resolved from its position among its siblings, so there’s nothing to set per item:

1
<loomi-timeline placement="alternate" anchor="big">
2
  <loomi-timeline-item date="10 days ago" content="You signed up"></loomi-timeline-item>
3
  <loomi-timeline-item date="8 days ago" content="Customer rep assigned"></loomi-timeline-item>
4
  <loomi-timeline-item date="2 days ago" content="Account is being reviewed"></loomi-timeline-item>
5
  <loomi-timeline-item content="Account activated"></loomi-timeline-item>
6
</loomi-timeline>

Colors

1
<loomi-timeline>
2
  <loomi-timeline-item date="10 days ago" content="You signed up" color="error" completed></loomi-timeline-item>
3
  <loomi-timeline-item date="8 days ago" content="Customer rep assigned" color="warning"></loomi-timeline-item>
4
  <loomi-timeline-item content="Account is being reviewed" color="success"></loomi-timeline-item>
5
</loomi-timeline>

Accessibility

For the library-wide baseline, see Foundations — Accessibility.

Responsive behavior

For the shared container and viewport rules, see Foundations — Responsive behavior.

Dark mode

For theme activation, token overrides, and contrast guidance, see Foundations — Dark mode.

Attributes

`<loomi-timeline-item>`

Attribute	Default	Description
`date`	(blank)	Date string.
`content`	(blank)	Entry text (or use the default slot).
`completed`	`false`	Filled anchor (+ check when `anchor="big"`). (boolean)
`anchor`	`small`	`small` \| `big` (big enables icons/avatars).
`icon`	(blank)	Anchor icon name (big anchor).
`avatar`	(blank)	Anchor image URL (big anchor).
`stacked`	`false`	Date above content vs. in a left column. (boolean)
`placement`	`left`	`left` \| `right` \| `alternate` — set on the `<loomi-timeline>` wrapper instead; it applies to every child.
`color`	`primary`	Any loomi color.

The trailing connector line and alternate left/right placement are both resolved automatically from the item’s position among its siblings — there is no last or per-item side attribute to set.

`<loomi-timeline>` (wrapper)

Shares stacked, completed, anchor, icon, color, and placement with all children.

Slots

Slot	Description
(default)	Content placed inside the component.
`content`	Custom body content.

Full Example

1
<loomi-timeline stacked anchor="big" color="error" placement="alternate" completed>
2
  <loomi-timeline-item
3
    date="9 days ago"
4
    avatar="/avatars/me.jpg"
5
    content="I am a timeline"
6
    completed
7
  ></loomi-timeline-item>
8
  <loomi-timeline-item date="2 days ago" content="Still going" completed="false"></loomi-timeline-item>
9
</loomi-timeline>

Framework integration

<loomi-timeline-item> and <loomi-timeline> are standard custom elements, so the browser can use them in plain HTML, Blade, React, Vue, Angular, Svelte, Astro, and most other frameworks. The important beginner rule is: install the package, import it once before the tag is rendered, then write the Loomi tag in your template.

Where to run commands

Run install commands from the app where you want to use this component. That means the folder that contains that app’s package.json. Do not run these install commands from packages/timeline unless you are editing LoomiUI itself.

1
cd /path/to/your-app
2
npm install @loomidev/timeline lit

If you are contributing to LoomiUI itself, first move to the top-level components folder. That is where the main package.json for all packages lives, and pnpm --filter ... commands should be run from there:

1
cd /path/to/your-copy-of-loomiui/components
2
pnpm --filter @loomidev/timeline build
3
pnpm --filter @loomidev/timeline typecheck

Choose your framework

Use the CDN version for prototypes, documentation pages, or a quick reproduction. The import map tells the browser where to find Lit, which Loomi components use internally.

1
<script type="importmap">
2
  { "imports": { "lit": "https://esm.sh/lit@3.3.3", "lit/": "https://esm.sh/lit@3.3.3/" } }
3
</script>
4
<script type="module" src="https://esm.sh/@loomidev/timeline"></script>
5

6
<loomi-timeline>
7
  <loomi-timeline-item date="09:00" completed>Order placed</loomi-timeline-item>
8
  <loomi-timeline-item date="10:30">Payment confirmed</loomi-timeline-item>
9
</loomi-timeline>

In Vite, Webpack, Parcel, Rollup, or a framework build pipeline, install the package and import it once in your main app JavaScript file. After that, you can use the Loomi tag anywhere in your app.

1
import "@loomidev/timeline";

Run the install command from your Laravel project root, then import the component in resources/js/app.js. If your project uses Laravel Vite, npm run dev and npm run build should also be run from the Laravel project root.

1
cd /path/to/your-laravel-app
2
npm install @loomidev/timeline lit
3
npm run dev

1
import "@loomidev/timeline";

1
<loomi-timeline>
2
  <loomi-timeline-item date="09:00" completed>Order placed</loomi-timeline-item>
3
  <loomi-timeline-item date="10:30">Payment confirmed</loomi-timeline-item>
4
</loomi-timeline>

React can render Loomi tags directly. If you are on React 18, or if you need to pass arrays, objects, or functions, use a ref and assign those values after the component mounts.

1
import "@loomidev/timeline";
2

3
export function LoomiExample() {
4
  return (
5
    <loomi-timeline>
6
      <loomi-timeline-item date="09:00" completed>Order placed</loomi-timeline-item>
7
      <loomi-timeline-item date="10:30">Payment confirmed</loomi-timeline-item>
8
    </loomi-timeline>
9
  );
10
}

If TypeScript does not recognize the Loomi tag in JSX, add it to your app’s JSX type declarations.

Import the package in the component that uses it, or once in your main Vue file. Vue templates can use Loomi tags directly. For arrays, objects, or functions, pass the value as a JavaScript property instead of as plain text.

1
<script setup>
2
import "@loomidev/timeline";
3
</script>
4

5
<template>
6
  <loomi-timeline>
7
    <loomi-timeline-item date="09:00" completed>Order placed</loomi-timeline-item>
8
    <loomi-timeline-item date="10:30">Payment confirmed</loomi-timeline-item>
9
  </loomi-timeline>
10
</template>

If Vue warns that the tag is an unknown component, configure compilerOptions.isCustomElement for tags that start with loomi- in your Vite or Vue config.

Import the package once and tell Angular to allow custom HTML tags with CUSTOM_ELEMENTS_SCHEMA. For NgModule apps, add the schema to the module instead of the standalone component.

1
import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
2
import "@loomidev/timeline";
3

4
@Component({
5
  selector: "app-root",
6
  standalone: true,
7
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
8
  template: `
9
    <loomi-timeline>
10
      <loomi-timeline-item date="09:00" completed>Order placed</loomi-timeline-item>
11
      <loomi-timeline-item date="10:30">Payment confirmed</loomi-timeline-item>
12
    </loomi-timeline>
13
  `,
14
})
15
export class AppComponent {}

Svelte can import the package inside a component script. Astro can import it in the frontmatter of the page or layout where the tag appears.

1
<script>
2
  import "@loomidev/timeline";
3
</script>
4

5
<loomi-timeline>
6
  <loomi-timeline-item date="09:00" completed>Order placed</loomi-timeline-item>
7
  <loomi-timeline-item date="10:30">Payment confirmed</loomi-timeline-item>
8
</loomi-timeline>

1
---
2
import "@loomidev/timeline";
3
---
4

5
<loomi-timeline>
6
  <loomi-timeline-item date="09:00" completed>Order placed</loomi-timeline-item>
7
  <loomi-timeline-item date="10:30">Payment confirmed</loomi-timeline-item>
8
</loomi-timeline>

Server-side rendering notes

Frameworks such as Next.js, Nuxt, SvelteKit, and Astro sometimes render HTML on the server before browser-only code runs. If your framework complains, move the Loomi import to client-side code. In Next.js, that usually means a component with "use client"; in Nuxt, it often means a .client.ts plugin.

Dependencies

@loomidev/core
@loomidev/icons