Timeline

Vertical and horizontal event timelines for audit logs, onboarding, and release history.

Overview

The Timeline component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Timelines visualize events in chronological order. They are ideal for activity logs, project history, and process tracking.

Mental model

A timeline is a vertical line with events positioned chronologically. Each event has a dot, timestamp, and description.

When to use

• Activity and audit logs • Project history and changelog • Process or journey tracking • Version history

When not to use

• Do not use for non-chronological data — use a list • Avoid for dense data — use a table • Do not use for future scheduling — use a calendar

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

Variants

Each variant communicates a different meaning. Choose based on priority, not aesthetics.

Single default variant.

Sizes

Size should match the importance and context of the component.

  • md — md size.

States

This component reacts seamlessly to the following interaction and data states:

  • default — Resting appearance before interaction.
  • hover — Pointer is over the element — visual feedback via color or shadow.
  • focus — Keyboard or tab focus — shows ring indicator for accessibility.
  • active — Currently selected or in use.
  • disabled — Non-interactive — grayed out, cursor not-allowed.

Anatomy

• Vertical line — the timeline axis • Dots — event markers • Event content — timestamp, title, description • Connector — line segments between events

Usage guidelines

  • Show most recent events at the top.
  • Use different dot styles for event types.
  • Keep descriptions concise.

Do and Don't

Do

  • Show newest first.
  • Use dot variations for types.
  • Keep descriptions short.

Don't

  • Do not show events out of order.
  • Do not overload with details.
  • Do not use for non-time-based data.

Accessibility

Events should have descriptive labels. Timeline is an ordered list (<ol>).

Role:list

Customization

Line and dot colors follow design tokens.

Compose with React cva()

Use the exportedcva() +cn() utilities to compose your own variant on top of the Byteion tokens.

import { cva, cn, type VariantProps } from '@byteion/react';

const myTimeline = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myTimeline>;

Compose with Vue cva()

Use the exportedcva() +cn() utilities inside standard Vue setup blocks.

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myTimeline = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myTimeline({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

HTML / JS events

No HTML runtime events are declared by this adapter.

React callbacks

No React callback events are declared by this adapter.

Vue emits

No Vue emitted events are declared by this adapter.

Remote / AJAX

This component does not implement Byteion JS remote loading. Use normal HTML form submission, framework state, or your application data layer around it.

API Reference

Static HTML composition.

HTML Data Attributes

No custom data attributes required.

React Props · TimelineProps

Extracted directly fromreact/src/components/Timeline.tsx.

export interface TimelineProps extends HTMLAttributes<HTMLOListElement> {
  children?: ReactNode;
}

Developer tips

• Store event timestamps as machine-readable values and render formatted text separately. • Group long timelines by date, version, or phase. • Keep marker tone rules consistent across the product (e.g. success = completed, danger = failed). • Use newest-first for audit logs and activity feeds. • Use natural chronological order for release or process timelines. • For long event histories, paginate or virtualize. • Use expandable detail for logs or metadata instead of placing everything inline.

Common mistakes

  • Using Timeline for non-chronological content.
  • Forgetting timestamps.
  • Mixing newest-first and oldest-first order in the same product area.
  • Using marker colour without text meaning.
  • Putting too much detail in every event.
  • Using Timeline when Table or DataTable is needed.
  • Making static events focusable.
  • Using raw colours instead of tokens.

Production usage tips

  • Test empty timeline, one event, many events, long titles, missing descriptions, and missing timestamps.
  • Test newest-first and oldest-first contexts.
  • Test long histories with pagination or grouping.
  • Test light mode, dark mode, and branded themes.
  • Test marker contrast and connector visibility.
  • For Laravel or server-rendered apps, render timelines from sorted event collections and use <time datetime="">.
  • For React or Vue SPAs, keep timeline data sorted before rendering and paginate long histories.
  • Coordinate Timeline with Avatar, Badge, Card, Accordion, Empty state, and Skeleton where needed.

Premium examples

Advanced patterns available in Byteion Pro:

• Audit log timeline with actor avatars • Order tracking timeline • Release history timeline • Deployment history timeline • Customer account history timeline • Timeline with grouped dates • Timeline with expandable event details • Timeline with type-colored dots and icons • Horizontal timeline for process flows

Related components

Unlock Premium Patterns

Get access to copy-paste ready Pro blocks, SaaS templates, and advanced data-tables built with this component.

Explore Pro Components