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

# Collection timeline

> Show records as bars across time, from a start date to an end date.

Add a timeline entry to `admin.views` to show each document as a bar from its start date to its end date, on a day, week or month scale. Bands split the bars by one field, as columns split a board. Include a list entry when users should be able to switch between table and timeline layouts.

See the complete [Collection views reference](https://docs.frogbot.ai/configuration/collections.md#collection-views).

## Timeline properties

| Property | Type | Required / default | Behavior |
| - | - | - | - |
| `type` | `'timeline'` | Yes | Selects the timeline layout. |
| `slug` | `string` | No; defaults to `'timeline'` | Unique normalized route and preference key. The first view uses the collection's root route. |
| `label` | `string` | No; defaults to `'Timeline'` | Label on the view's tab. |
| `icon` | `AdminIcon` | No; `'timeline'` | Icon on the view's tab. |
| `start` | `string` | Yes | Dot path to the date field each bar starts on. |
| `end` | `string` | No | Dot path to the date field each bar ends on. Without it, every bar is one day long and can't be resized. |
| `groupBy` | `string` | No | Dot path to the field that splits the timeline into bands. It takes the same fields as a [board's `groupBy`](https://docs.frogbot.ai/admin/collection-board). Without it, the timeline has one band. |
| `color` | `string` | No | Dot path to a select or radio field. When the field has [option colors](https://docs.frogbot.ai/fields/select.md#option-colors), each bar takes its option's color, and options without one are gray. |
| `scales` | `TimelineScale[]` | No; `['week', 'month', 'day']` | Zoom levels people can switch between, in display order. The first opens by default. Each is `'day'`, `'week'` or `'month'`. |
| `filter` | `Where` | No | Invisible base filter applied to every timeline query, as plain data. |
| `defaultFields` | `string[]` | No | Not read by the timeline: each bar shows the document's title. |
| `defaultSort` | `Sort` (`string \| string[]`) | No | Not read by the timeline: bars are ordered by their dates. |
| `searchableFields` | `string[]` | No | Not read by the timeline. Its search uses the list view's `searchableFields`, plus `useAsTitle`. |
| `pagination` | `ViewPagination` | No | Accepted for consistency with other views, but timeline views ignore it. Each visible range loads at most 1000 records. |
| `access` | `({ req }) => boolean \| Promise<boolean>` | No; collection access | Controls whether the current user can open the timeline without replacing collection operation access. |
| `components` | `ViewComponents & TimelineComponents` | No | Configures shared view slots and timeline components. |

## Timeline components

| Property | Type | Required / default | Behavior |
| - | - | - | - |
| `actions` | `FrogBotComponent[]` | No; `[]` | Renders in the page header, top right. |
| `toolbar` | `FrogBotComponent[]` | No; `[]` | Renders in the timeline's view controls, before Filters. |
| `menuItems` | `FrogBotComponent[]` | No; `[]` | Adds entries to the timeline menu. |
| `beforeView` | `FrogBotComponent[]` | No; `[]` | Renders inside the view frame before the header. |
| `afterView` | `FrogBotComponent[]` | No; `[]` | Renders inside the view frame after the timeline. |
| `beforeTimeline` | `FrogBotComponent[]` | No; `[]` | Renders before the timeline. |
| `afterTimeline` | `FrogBotComponent[]` | No; `[]` | Renders after the timeline. |
| `Bar` | `FrogBotComponent` | No; the document's title | Replaces each bar's body and receives the document as its `row` prop. |
| `NoResults` | `FrogBotComponent` | No; built-in empty state | Shown above the timeline when its filters match no records. The timeline stays. |

```ts theme={"theme":"tokyo-night"}
export const Tasks: CollectionConfig = {
  slug: 'tasks',
  admin: {
    useAsTitle: 'title',
    views: [
      { type: 'list', defaultFields: ['title', 'project', 'status', 'dueDate'] },
      {
        type: 'timeline',
        start: 'startDate',
        end: 'dueDate',
        groupBy: 'project',
        color: 'status',
      },
    ],
  },
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'project', type: 'relationship', relationTo: 'projects' },
    { name: 'status', type: 'select', options: ['todo', 'in-progress', 'done'] },
    { name: 'startDate', type: 'date' },
    { name: 'dueDate', type: 'date' },
  ],
}
```

Startup checks the view's settings:

| Setting | Must resolve to |
| - | - |
| `start`, `end` | Date fields. |
| `color` | A select or radio field. |
| `groupBy` | A field a board can group by. |
| `scales` | A non-empty list of distinct `'day'`, `'week'`, and `'month'` values. |

Nested fields use dot paths such as `schedule.startsAt`.

## Scales and bands

| Scale | Shows | The header's arrows move |
| - | - | - |
| Day | Two weeks, from the start of the current week. | A week. |
| Week | Eight weeks, starting two weeks back. | Four weeks. |
| Month | Three months, from the start of the current month. | A month. |

**Today** comes back to the current date. On a narrow screen, the band names stay pinned on the left and the bars scroll sideways inside the timeline.

With `groupBy`, bands follow the board's rules: a select, radio or checkbox field shows every option in its declared order, even with no records, and other fields show the values records have. Records with no value sit in a last **No value** band, shown when it has any. Bars that overlap within a band stack into rows; bars that don't share a row.

## Dates and time zones

Bars land on the same days as in the [calendar](https://docs.frogbot.ai/admin/collection-calendar.md#time-zones-and-all-day-dates): a moment shows on its day in the viewer's browser time zone, and a date field with `pickerAppearance` `'dayOnly'` or `'monthOnly'` shows on its saved date for every viewer.

* A record with both dates is a bar from its start day to its end day. A timed end at exactly midnight ends on the day before, with or without a start date.
* A record with only one of the two dates is a one-day bar on that date. Dragging its free edge fills in the other date on the day it is dropped, at the existing date's time of day, or at noon when the existing date is date-only.
* A record with neither date isn't shown.

Each visible range loads only the records that overlap it, with the view's filter and the current search, at most 1000 at a time.

## Moving and resizing

* **Move.** Drag a bar sideways to move it by whole days. Both dates move and keep their time of day, even across a daylight-saving change.
* **Resize.** Drag a bar's left edge to change its start date, and its right edge to change its end date. An edge stops where the bar is one day long, so the end never moves before the start.

On a touch screen:

* A sideways drag on a bar moves it, a vertical swipe scrolls the page, and a drag on the empty track scrolls the timeline.
* Edge handles are 44px wide and reach up to 23px into the bar.

On a narrow bar, each handle covers at most a quarter of the bar, so the middle always opens or moves the bar.

Dragging a bar never changes its band: change the grouped field in the record. Each change is a normal collection update, with access checks, validation and hooks. If it fails, the bar goes back and the error shows. Users without update access to the date fields can view bars but not move them.

Click a bar, or focus it and press Enter, to open the record in the [record panel](https://docs.frogbot.ai/admin/record-panel.md). Saving or deleting there updates the timeline.

The selected scale and date are saved per user and view. URL values take precedence over saved preferences, which take precedence over the configured defaults.

With the collection's [`admin.useAsDone`](https://docs.frogbot.ai/configuration/collections#done-records) set, done records show a green check and a muted title. The record open in the panel shows the shared selected style.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.