# Activity Timeline (`activity-timeline`) - SignalOS widget

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

- **Version:** 0.1.1
- **Kind:** widget · **Category:** data-display
- **Install:** `npx shadcn@latest add @signalos/activity-timeline`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/skeleton, @signalos/utils
- **npm dependencies:** lucide-react@^1.7.0, class-variance-authority@^0.7.1
- **Files installed:** `src/components/widgets/activity-timeline/ActivityTimeline.tsx`, `src/components/widgets/activity-timeline/ActivityTimeline.types.ts`, `src/components/widgets/activity-timeline/ActivityTimeline.variants.tsx`, `src/components/widgets/activity-timeline/ActivityTimeline.utils.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import { ActivityTimeline } from "@/components/widgets/activity-timeline/ActivityTimeline"
```

## 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

### `TimelineStatus`

```ts
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"
```

### `ActivityTimelineVariant`

```ts
export type ActivityTimelineVariant =
  /**
   * Standard timeline with normal spacing and content.
   */
  | "default"

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

### `TimelineItem`

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

### `ActivityTimelineProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly TimelineItem[]` | yes | - | Collection of timeline items to display. |
| `variant` | `ActivityTimelineVariant \| undefined` | no | `"default"` | Controls the overall layout of the timeline.  - `default` → Standard spacing - `compact` → Reduced spacing |
| `loading` | `boolean \| undefined` | no | `false` | Displays a loading state.  Typically renders a skeleton placeholder instead of the timeline items. |
| `error` | `boolean \| undefined` | no | `false` | Displays an error state instead of the timeline. |
| `errorMessage` | `ReactNode` | no | - | Custom error message shown when `error` is true.  Example: "Unable to load activity history." |
| `maxItems` | `number \| undefined` | no | - | Maximum number of timeline items to render.  Useful for showing only the most recent activities.  Example: `maxItems={5}` |
| `className` | `string \| undefined` | no | - | Additional CSS or Tailwind classes applied to the root timeline container. |
| `data-testid` | `string \| undefined` | no | - | Test identifier used by automated testing tools.  Example: ```tsx data-testid="activity-timeline" ``` |

### `ActivityTimelineSkeletonProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `className` | `string \| undefined` | no | - | Additional CSS or Tailwind classes applied to the skeleton container. |
| `itemCount` | `number \| undefined` | no | `5` | Number of skeleton timeline items to render. |
| `variant` | `"default" \| "compact" \| undefined` | no | `"default"` | Layout variant for the skeleton.  Should match the layout of the actual timeline. |

## Changelog

# activity-timeline

## 0.1.1

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


## 0.1.0

- Initial release.