> ## Documentation Index
> Fetch the complete documentation index at: https://woltz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Timeline

> A timeline component with date-based grouping and infinite scroll support.

<a href="https://react-rich-domain.netlify.app/#timeline" target="_blank">Live Demo</a>

## Instalation

<CodeGroup>
  ```bash npm theme={null}
  npx shadcn add "https://tarcisioandrade.github.io/rich-domain/packages/react-rich-domain/public/r/user-timeline.json"
  ```

  ```bash pnpm theme={null}
  pnpm dlx shadcn add "https://tarcisioandrade.github.io/rich-domain/packages/react-rich-domain/public/r/user-timeline.json"
  ```

  ```bash yarn theme={null}
  yarn dlx shadcn add "https://tarcisioandrade.github.io/rich-domain/packages/react-rich-domain/public/r/user-timeline.json"
  ```
</CodeGroup>

#### Features

* Infinite scroll with React Query
* Automatic date grouping (hour/day/week/month/year)
* Relative time labels ("Today", "Yesterday", etc.)
* Integrated search and filtering
* Customizable event rendering
* Timeline layout options (default or horizontal sidebar)

#### Basic Usage

```tsx theme={null}
import { useCriteriaTimeline } from "@/hooks/use-criteria-timeline";
import { DataTimelineCriteria } from "@/components/data-timeline-criteria/data-timeline-criteria";
import type { QueryFilter } from "@/lib/filter-utils";

interface Activity {
  id: string;
  title: string;
  description: string;
  createdAt: string;
  type: "create" | "update" | "delete";
}

const filterFields: QueryFilter[] = [
  {
    field: "type",
    fieldLabel: "Type",
    type: "string",
    options: [
      { label: "Created", value: "create" },
      { label: "Updated", value: "update" },
      { label: "Deleted", value: "delete" },
    ],
  },
];

function ActivityTimeline() {
  const timeline = useCriteriaTimeline<Activity>(
    ["activities"],
    getActivities,
    {
      dateField: "createdAt",
      groupBy: "day",
      filterFields,
      pageSize: 20,
    }
  );

  return (
    <DataTimelineCriteria
      timeline={timeline}
      renderEvent={(activity) => (
        <div className="space-y-1">
          <h3 className="font-semibold">{activity.title}</h3>
          <p className="text-sm text-muted-foreground">
            {activity.description}
          </p>
        </div>
      )}
      toolbarLayout="default" // or "none" for no toolbar
    />
  );
}
```

#### Timeline Options

```tsx theme={null}
interface UseCriteriaTimelineOptions<T> {
  // Required
  dateField: FieldPath<T>; // Field to group by

  // Grouping
  groupBy?: "hour" | "day" | "week" | "month" | "year"; // Default: "day"
  sortDirection?: "asc" | "desc"; // Default: "desc"

  // Filter configuration
  filterFields?: QueryFilter[];

  // Search
  searchDebounceMs?: number; // Default: 300

  // React Query options
  pageSize?: number;
  enabled?: boolean;
  staleTime?: number;
  gcTime?: number;
}
```

#### Toolbar Layouts

```tsx theme={null}
// Default layout - toolbar on top
<DataTimelineCriteria
  timeline={timeline}
  renderEvent={renderEvent}
  toolbarLayout="default"
/>

// No toolbar - pure timeline
<DataTimelineCriteria
  timeline={timeline}
  renderEvent={renderEvent}
  toolbarLayout="none"
/>
```