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

# Timeline

> Timeline.vue Component Documentation

The `Timeline.vue` component is a dynamic, event-driven timeline that allows users to navigate through a sequence of events. Events are displayed in a paginated format, and users can jump to specific dates or move to newer or older events.

***

## Features

<CardGroup cols={2}>
  <Card title="Dynamic Event Rendering" icon="square-1">
    Displays a subset of events based on pagination, allowing users to browse through a large event list efficiently.
  </Card>

  <Card title="Navigation Controls" icon="square-2">
    Includes buttons to navigate between the newest, newer, older, or oldest events, providing a smooth browsing experience.
  </Card>

  <Card title="Date Selection" icon="square-3">
    Allows users to jump to a specific date using a dropdown selector, enabling quick access to events from a particular day.
  </Card>

  <Card title="Customizable Appearance" icon="square-4">
    Supports custom dot styles for each event, allowing for personalized and visually distinct timeline entries.
  </Card>
</CardGroup>

***

## Usage

### Basic Example

```vue theme={null}
<template>
  <Timeline
    :events="eventsData.events"
    :page-length="3"
    dot-classes="bg-blue-500 rounded-full w-4 h-4"
    :format="{
      weekday: 'long',
      year: 'numeric',
      month: 'long',
      day: 'numeric',
    }"
  >
    <template #default="{ event: event }">
      <b>{{ event.title }}</b>
    </template>
  </Timeline>
</template>

<script setup>
import { reactive } from 'vue';
import { Timeline } from '@robojuice/velure-ui';

const eventsData = reactive({
  events: [
    { id: 1, title: 'Event 1', datetime: '2024-11-20T10:00:00Z', description: 'Description for event 1' },
    { id: 2, title: 'Event 2', datetime: '2024-11-21T12:00:00Z', description: 'Description for event 2' },
    { id: 3, title: 'Event 3', datetime: '2024-11-22T14:00:00Z', description: 'Description for event 3' },
    { id: 4, title: 'Event 4', datetime: '2024-11-23T16:00:00Z', description: 'Description for event 4' },
    { id: 5, title: 'Event 5', datetime: '2024-11-24T18:00:00Z', description: 'Description for event 5' },
  ],
});
</script>
```

***

## Props

<ParamField path="events" type="array" default="[]">
  Array of event objects, each containing `id`, `title`, `datetime`, and `description`.
</ParamField>

<ParamField path="dotClasses" type="string" default="''">
  Custom CSS classes for the event dots.
</ParamField>

<ParamField path="pageLength" type="number" default="5">
  Number of events displayed per page.
</ParamField>

<ParamField path="format" type="object">
  Default value: `{ weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }`. [Formatting options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#date-time_component_options) for event dates using [Date.toLocaleDateString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString).
</ParamField>

***

## Example Use Cases

### Timeline with Custom Dot Style

```vue theme={null}
<Timeline
  :events="eventsData.events"
  dot-classes="bg-green-500 rounded-full w-4 h-4"
  :page-length="3"
>
  <template #default="{ event }">
    <div>
      <b>{{ event.title }}</b>
      <p>{{ event.description }}</p>
    </div>
  </template>
</Timeline>
```

### Date-Specific Navigation

```vue theme={null}
<Timeline
  :events="eventsData.events"
  :page-length="5"
  :format="{ weekday: 'short', month: 'short', day: '2-digit' }"
>
  <template #default="{ event }">
    <div>
      <b>{{ event.title }}</b>
      <small>{{ event.datetime }}</small>
    </div>
  </template>
</Timeline>
```

***

## Notes

* **Pagination**: Use the `pageLength` prop to control the number of events displayed at a time.
* **Custom Event Rendering**: Leverage the default scoped slot to fully customize the display of events.
* **Dot Customization**: Use the `dotClasses` prop to style the dots marking each event in the timeline.

For further customization, refer to the component's source code.