Bases Timeline View

obsidian-bases-timeline-view

Timeline view for Obsidian Bases.

Chinese documentation: 中文版.md.

Features

• Timeline: Plot notes on a timeline for a clear view of temporal information.
• Grouping: Group timeline items by any note field and visually separate related events.
• Background and markers (Bases): In addition to regular timeline items, support drawing backgrounds and markers.
• Render API: Expose an API for other scripts to customize drawing and extend the timeline.
• Preview: Timeline items support Obsidian's built-in hover preview for immersive reading.

Example

Basic usage

To draw a timeline, add properties to your notes, for example:

start: 2025-01-01
end: 2025-01-04
content: title of the item
tags:

- moment

Then create a Base and add a timeline view:

filters:
  and:
    - file.tags.contains("moment")
    - and:
        - file.ctime >= "2025-01-01"
        - file.ctime <= "2025-12-31"
views:
  - type: timeline-view
    name: moment of 2025

The result looks roughly like this:

timeline-view reads frontmatter from each file and plots it on the timeline. Default frontmatter properties:

Custom fields

If you prefer not to use the default property names, specify custom fields in the view, for example:

filters:
  and:
    - file.tags.contains("moment")
    - and:
        - file.ctime >= "2025-01-01"
        - file.ctime <= "2025-12-31"
views:
  - type: timeline-view
    name: moment of 2025
    startField: note.startData
    endField: note.endData

Make sure these properties are defined in your notes.

Grouping

With Obsidian 1.10 or later, use group by to group timeline items, for example:

Background and markers

Use backgroundWhen and markerWhen to decide which notes should be drawn as backgrounds or markers. Example:

filters:
  or:
    - file.tags.contains("moment")
    - file.tags.contains("phase")
    - file.tags.contains("milestone")
formulas:
  isPhase: 'file.tags.contains("phase")'
  isMilestone: 'file.tags.contains("milestone")'
views:
  - type: timeline-view
    name: moment of 2025
    startField: note.start
    endField: note.end
    backgroundWhen: formula.isPhase
    markerWhen: formula.isMilestone

• Background notes need start and end in frontmatter.
• Marker notes need start (as the vertical line time); content / file name is used as the marker label.
• When multiple roles match, priority is: marker > background > item.
• Backgrounds also support grouping and can be drawn by group.

Custom styles

Use Obsidian's built-in style extensions together with this plugin's hooks to customize the timeline look.

Style via cssclasses

By default the plugin reads Obsidian's built-in cssclasses and sets them as the vis-timeline item/background className. You can also point the class name field in the view to another property.

cssclasses:

- phase-bg

.vis-item.phase-bg {
	background-color: rgba(211, 211, 211, 0.45);
	border-color: #d3d3d3;
}

Style via data attributes

Timeline items also expose tags and frontmatter as data- attributes for CSS selectors, for example:

.vis-item:has(.timeline-item[data-tags~='#projects']) {
	border-width: 1px;
	border-style: solid;
}

.vis-item:has(
	.timeline-item[data-tags~='#projects'][data-status='not started']
) {
	background-color: rgba(211, 211, 211, 0.45);
	border-color: #d3d3d3;
}

• #projects is a tag; replace it with any tag
• data-status="not started" comes from frontmatter (status); replace it with any field

API

When you need to query data yourself (for example with DataviewJS), use the plugin's exposed api:

Plugin id: bases-timeline-view.

const api = app.plugins.plugins['bases-timeline-view']?.api;
if (!api) {
	// Plugin not enabled
	dv.paragraph('Please update and enable Bases Timeline View');
} else {
	// Call api.render / api.dv.render
}

Full parameters and types: API reference.

Quick example: api.render

```dataviewjs
const api = app.plugins.plugins['bases-timeline-view']?.api;
if (!api) {
  dv.paragraph('请先启用 Bases Timeline View 插件。');
} else {
  const items = [
    {
      id: 'notes/事件-甲.md',
      start: '2025-01-01',
      end: '2025-01-03',
      content: '事件甲',
      group: '工程',
    },
    {
      id: 'notes/事件-乙.md',
      start: '2025-02-10',
      content: '事件乙',
      group: '设计',
    },
  ];

  const backgrounds = [
    {
      id: 'notes/Q1.md',
      start: '2025-01-01',
      end: '2025-03-31',
      content: 'Q1',
      className: 'phase-bg',
    },
  ];

  const markers = [
    { id: 'launch', time: '2025-03-01', title: '发布' },
  ];

  api.render(this.container, { items, backgrounds, markers });
}
```

Quick example: api.dv.render

```dataviewjs
const api = app.plugins.plugins['bases-timeline-view']?.api;
if (!api?.dv) {
  dv.paragraph('请先启用 Bases Timeline View 插件。');
} else {
	api.dv.render(this.container, {
		items: dv.pages('#event'),
		backgrounds: dv.pages('#phase'),
		markers: dv.pages('#milestone'),
	});
}

```

Commands

In a Markdown editor, open the command palette and run:

• Insert custom render template — inserts the api.render DataviewJS example at the cursor
• Insert Dataview render template — inserts the api.dv.render DataviewJS example at the cursor

Previewing these blocks requires the Dataview plugin.

Tips

• Bases views and api / api.dv.render share the same date normalization (string, Date, number → moment → YYYY-MM-DD).
• Incomplete inputs like "2025" or "2025-01" are completed by moment into full dates (for example 2025-01-01). If a property only needs to represent a year or year-month, you can use a text type, but rendering still normalizes to YYYY-MM-DD.

Installation

Three ways:

• (Recommended)Install from Obsidian Community Plugins, search bases timeline view to install
• Manual install
  • Download the latest release from GitHub Releases
  • Create a folder bases-timeline-view under .obsidian/plugins/
  • Put the downloaded files into that folder
  • Reload Obsidian
  • Enable it in Settings → Community plugins
• Install via BRAT
  • If you don't have it yet, install BRAT
  • Enable BRAT in Settings → Community plugins
  • Open the command palette (Ctrl+P) and run BRAT: Plugins: Add a beta plugin for test
  • Enter the repository URL: https://github.com/xjiaxiang/obsidian-bases-timeline-view
  • Select the latest version
  • Click Add plugin to install
  • If it is not enabled automatically, enable bases-timeline-view in Settings → Community plugins

Other

• Thanks to vis-timeline and obsidian timeline