Component Props

All props accepted by the <TempisTimeline> Vue component.

Props

Prop	Type	Default	Description
`items`	`TempisTimelineItem[]`	required	Timeline items to display.
`categories`	`TempisTimelineCategory[]`	—	Item categories.
`bands`	`TempisTimelineBand[]`	—	Timeline bands.
`dependencies`	`TempisTimelineDependency[]`	—	Item dependency arrows.
`selection`	`(string \| number)[]`	—	Selected item IDs (`v-model:selection`). Enables controlled selection when provided.
`options`	`TempisTimelineConfig`	`{}`	Configuration options (see Options).
`width`	`string \| number`	`"100%"`	Canvas width.
`height`	`string \| number`	`300`	Canvas height.
`wrapperClass`	`string`	—	CSS class for the wrapper `<div>`.
`wrapperStyle`	`CSSProperties`	—	Inline styles for the wrapper `<div>`.

Events

Event	Payload	Description
`item-click`	`id: string \| number`	Item clicked.
`item-double-click`	`id: string \| number`	Item double-clicked.
`item-context-click`	`id: string \| number, position: { x, y }`	Item right-clicked (context menu).
`item-hover`	`id: string \| number \| null`	Pointer enters an item or leaves all items (`null`).
`update:selection`	`(string \| number)[]`	Selection changed. Emitted only in controlled mode. Use with `v-model:selection`.
`range-change`	`start: Date, end: Date`	Visible range changed.
`group-toggle`	`group: string, collapsed: boolean`	A group header was clicked to collapse or expand.

Selection Modes

Selection behaviour depends on two things: the selection mode in options ("none", "single", or "multi") and whether you bind v-model:selection.

Uncontrolled (default)

Don't pass the selection prop. The timeline manages selection state internally — items highlight immediately on click.

<TempisTimeline
  :items="items"
  :options="{ selection: 'multi' }"
/>

Controlled (v-model)

Bind v-model:selection to own the selection state. The timeline will not update visually until you update the bound ref. This lets you validate, filter, or transform selection changes before applying them.

<script setup lang="ts">
import { ref } from 'vue'
import { TempisTimeline } from '@tempis/vue'

const selectedIds = ref<(string | number)[]>([])
</script>

<template>
  <p>Selected: {{ selectedIds }}</p>
  <button @click="selectedIds = []">Clear</button>
  <TempisTimeline
    v-model:selection="selectedIds"
    :items="items"
    :options="{ selection: 'multi' }"
  />
</template>

Reactive vs Structural

items, categories, bands, dependencies, and selection are reactive — changes are synced to the existing instance via watch without recreating it. The options prop is structural — when its serialised value changes, the entire timeline instance is destroyed and recreated.

Example

<script setup lang="ts">
import { ref } from 'vue'
import { TempisTimeline, type TempisTimelineItem } from '@tempis/vue'

const items = ref<TempisTimelineItem[]>([
  { id: 1, label: 'Item 1', start: '2026-03-01', end: '2026-03-15', category: 'cat-a' },
  { id: 2, label: 'Item 2', start: '2026-03-10', end: '2026-03-25', category: 'cat-b' },
])

const categories = [
  { name: 'cat-a', label: 'Category A', style: { backgroundColor: '#6366f1' } },
  { name: 'cat-b', label: 'Category B', style: { backgroundColor: '#10b981' } },
]

function onItemClick(id: string | number) {
  console.log('Clicked:', id)
}
</script>

<template>
  <TempisTimeline
    :items="items"
    :categories="categories"
    :options="{
      responsive: true,
      selection: 'single',
      legend: { position: 'top' },
      range: { start: '2026-02-25', end: '2026-04-01', position: 'bottom' }
    }"
    :height="350"
    @item-click="onItemClick"
  />
</template>