Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Vue 3 Timeline Chart component

A simple yet versatile vue3 component that allows you to plot points or ranges on a timeline. You can zoom in/out, scroll horizontally and update content dynamically.

Feel free to report issues, make PR's and start discussions.


timeline with customized styling


  • Zooming
  • Infinite scrolling
  • Plotting ranges, points, markers and backgrounds
  • Adjustable timestamp labels per scale
  • Customizable


npm add vue-timeline-chart


  :minViewportDuration="1000 * 60"
  :maxViewportDuration="1000 * 60 * 60 * 24 * 7"
  <template #group-label="{ group }">
    {{ group.content }}

  <template #item="{item}">
      :title="item.title || null"
      style="inset: 0; position: absolute;"


Option Type Default Description
groups TimelineGroup[] [] Define (rows)
items TimelineItem[] [] Items to display
markers TimelineMarker[] [] Markers to display
viewportMin number undefined Minimum timestamp of the viewport (prevents scrolling to before this point)
viewportMax number undefined Maximum timestamp of the viewport (prevents scrolling past this point)
minViewportDuration number 60000 (1 min) Minimum duration of the viewport in ms (limits zooming in)
maxViewportDuration number undefined Maximum duration of the viewport in ms (limits zooming out)
initialViewportStart number undefined Initial start timestamp of the viewport
initialViewportEnd number undefined Initial end timestamp of the viewport
renderTimestampLabel function(timestamp: number, scale: { unit: string, step: number}) undefined Custom function to render timestamp labels
fixedLabels boolean false Whether to display group labels on top of the timeline
minTimestampWidth number 100 Minimum width a timestamp label should have in px (determines how many timestamps should be displayed)
activeItems TimelineItem['id'][] [] IDs of items that should have an active class


Slot Props Description
timestamp { timestamp: number, scale: { unit: string, step: number } } Timestamp label
group-label { group: TimelineGroup } Group label
items-GROUPID { group: TimelineGroup, itemsInViewport: TimelineItem[], viewportStart: number, viewportEnd: number } Slot for all items within a group, useful when rendering the items manually (e.g. when using a chart or canvas)
item { item: TimelineItem } Item content


Event Arguments Description
click {time: number, event: MouseEvent, item: TimelineItem | null} Click event on the timeline
contextmenu {time: number, event: MouseEvent, item: TimelineItem | null} Right-click event on the timeline
mousemoveTimeline {time: number, event: MouseEvent} Mousemove event on the timeline
mouseleaveTimeline {event: MouseEvent} Mouseleave event on the timeline
changeViewport { start: number, end: number } Visible range has changed
changeScale { unit: string, step: number } Visible scale (minutes/hours/days/etc.) has changed

The time argument is the position (in ms) in the timeline where the mouse is hovering.


TimelineGroups are the rows in the timeline with items.

Option Type Default Description
id string (required) Unique ID, to bind items to
content string (required) Group label
className string '' CSS class(es)


TimelineItems can be points, ranges, backgrounds or markers. They are assigned to a group by their group property.

Option Type Default Description
id string undefined Unique ID, to match with activeItems prop
start number (required) Timestamp
end number (required for range and background) Timestamp, only used for type range and background
className string '' CSS class(es)
type string (required) Type of item, one of: point, range, background or marker
cssVariables Record<string, string> {} CSS variables to apply to the item (e.g. { '--height': '20%' })


To improve performance, you can add markers as an individual prop, instead of together with items. This allows you to update the position of a marker (e.g. to show the current time) while keeping the rest of the items cached.

Option Type Default Description
id string undefined Unique ID, to match with activeItems prop
start number (required) Timestamp
className string '' CSS class(es)
type string (required) marker


Install dependencies:

pnpm install

Dev server with live reloading

pnpm start

Building the application and watching for changes

pnpm dev

Recommended IDE Setup

  1. Disable the built-in TypeScript Extension
    1. Run Extensions: Show Built-in Extensions from VSCode's command palette
    2. Find TypeScript and JavaScript Language Features, right click and select Disable (Workspace)
  2. Reload the VSCode window by running Developer: Reload Window from the command palette.