Activity Timeline

v0.1.1

Vertical activity/event timeline with status-colored indicators and a compact/default layout variant.

View as Markdown

Install

npx shadcn@latest add @signalos/activity-timeline

Requires a configured @signalos registry and a valid SIGNALOS_REGISTRY_TOKEN - get access. Registry dependencies (@signalos/tokens, @signalos/skeleton, @signalos/utils) are pulled automatically.

Preview

Example & code

activity-timeline.example.tsx
// Example: wiring the shell in a plain React app (router-agnostic).
// In Next.js, pass `activePath={usePathname()}` and a Link adapter:
//   LinkComponent={({ href, ...p }) => <Link href={href} {...p} />}
import {
  Activity,
  AlertTriangle,
  CheckCircle2,
  Database,
  ShieldAlert,
  UserPlus,
  XCircle,
} from "lucide-react"

import { ActivityTimeline } from "./ActivityTimeline"
import { TimelineItem } from "./ActivityTimeline.types"

export const activityTimelineData: TimelineItem[] = [
  {
    id: 1,
    title: "Deployment Started",
    description: "Production deployment for version v2.8.1 has been initiated.",
    timestamp: "Just now",
    status: "info",
    icon: <Activity className="h-3 w-3" />,
  },
  {
    id: 2,
    title: "Build Completed",
    description: "Application build completed successfully.",
    timestamp: "3 min ago",
    status: "success",
    icon: <CheckCircle2 className="h-3 w-3" />,
  },
  {
    id: 3,
    title: "High Memory Usage",
    description: "Memory utilization exceeded 85% on Server-02.",
    timestamp: "10 min ago",
    status: "warning",
    icon: <AlertTriangle className="h-3 w-3" />,
  },
  {
    id: 4,
    title: "Database Backup",
    description: "Nightly PostgreSQL backup completed successfully.",
    timestamp: "22 min ago",
    status: "default",
    icon: <Database className="h-3 w-3" />,
  },
  {
    id: 5,
    title: "Authentication Failed",
    description: "Multiple failed login attempts detected from an unknown IP.",
    timestamp: "35 min ago",
    status: "error",
    icon: <ShieldAlert className="h-3 w-3" />,
  },
  {
    id: 6,
    title: "New Team Member",
    description: "Sarah Johnson joined the Analytics workspace.",
    timestamp: "1 hour ago",
    status: "info",
    icon: <UserPlus className="h-3 w-3" />,
  },
  {
    id: 7,
    title: "Service Restored",
    description: "API connectivity has been restored after maintenance.",
    timestamp: "2 hours ago",
    status: "success",
    icon: <CheckCircle2 className="h-3 w-3" />,
  },
  {
    id: 8,
    title: "Unexpected Error",
    description: "Background synchronization failed due to a timeout.",
    timestamp: "3 hours ago",
    status: "error",
    icon: <XCircle className="h-3 w-3" />,
  },
]
export default function Example() {
  return (
    <div className="flex h-[480px] overflow-hidden rounded-lg  [&_aside]:!flex [&_aside]:h-full">
      <ActivityTimeline items={activityTimelineData} />
    </div>
  )
}

Props

TimelineItem

PropTypeDefaultDescription
id*number-Unique identifier for the timeline item. Used as the React key when rendering the list.
title*ReactNode-Main title or heading of the activity. Example: - "User Created" - "Invoice Approved"
descriptionReactNode-Additional details describing the activity. Displayed below the title.
timestampReactNode-Date, time, or timestamp associated with the activity. Example: - "2 minutes ago" - "10 Jul 2026, 10:30 AM"
statusTimelineStatus | undefined"default"Visual status of the activity. Determines the color or appearance of the status indicator.
iconReactNode-Optional custom icon displayed beside the activity. Example: ```tsx <CheckCircle /> <AlertTriangle /> <Clock /> ```

ActivityTimelineProps

PropTypeDefaultDescription
items*readonly TimelineItem[]-Collection of timeline items to display.
variantActivityTimelineVariant | undefined"default"Controls the overall layout of the timeline. - `default` → Standard spacing - `compact` → Reduced spacing
loadingboolean | undefinedfalseDisplays a loading state. Typically renders a skeleton placeholder instead of the timeline items.
errorboolean | undefinedfalseDisplays an error state instead of the timeline.
errorMessageReactNode-Custom error message shown when `error` is true. Example: "Unable to load activity history."
maxItemsnumber | undefined-Maximum number of timeline items to render. Useful for showing only the most recent activities. Example: `maxItems={5}`
classNamestring | undefined-Additional CSS or Tailwind classes applied to the root timeline container.
data-testidstring | undefined-Test identifier used by automated testing tools. Example: ```tsx data-testid="activity-timeline" ```

ActivityTimelineSkeletonProps

PropTypeDefaultDescription
classNamestring | undefined-Additional CSS or Tailwind classes applied to the skeleton container.
itemCountnumber | undefined5Number of skeleton timeline items to render.
variant"default" | "compact" | undefined"default"Layout variant for the skeleton. Should match the layout of the actual timeline.

Supporting types

export type TimelineStatus =
  /** Neutral/default state. */
  | "default"

  /** Indicates a successful action or completed event. */
  | "success"

  /** Indicates a warning or action requiring attention. */
  | "warning"

  /** Indicates an error or failed event. */
  | "error"

  /** Indicates informational or general events. */
  | "info"
export type ActivityTimelineVariant =
  /**
   * Standard timeline with normal spacing and content.
   */
  | "default"

  /**
   * Compact timeline with reduced spacing for
   * displaying more items in less space.
   */
  | "compact"

npm dependencies

lucide-react@^1.7.0class-variance-authority@^0.7.1

Changelog

activity-timeline

0.1.1

  • Content sync fix to bring source in line with published registry payload.

0.1.0

  • Initial release.