README file from
Githubobsidian-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:
| Property | Description | Required | Example | Notes |
|---|---|---|---|---|
| start | Start date | No | 2025-01-01 | |
| date | Start date | No | 2025-01-01 | Used when start is not set |
| end | End date of the item | No | 2025-01-04 | |
| content | Item content / title | No | title of the item | Falls back to the file name when unset |
| startLabel | Display label for the start date | No | start | |
| endLabel | Display label for the end date | No | end | |
| cssclasses | CSS classes attached to the vis item | No | phase-bg | Built-in Obsidian list property; join multiple with spaces |
Supported time formats:
- Text (string):
YYYY, e.g.2025→2025-01-01YYYY-MM, e.g.2025-03→2025-03-01YYYY-MM-DD, e.g.2025-03-15- ISO date-time, e.g.
2025-03-15T12:30:00; only the date part is used- Signed/extended years, e.g.
-0044,-0044-03-15,+010000-01-01- Number: an integer year, e.g.
2025→2025-01-01(not a timestamp)- Date: an Obsidian frontmatter property of type Date / Date & time; the selected date is used as-is
Month and day must be zero-padded (
2025-1,2025-3-5are not supported);2025/03/15, natural-language dates, and impossible dates such as2025-02-30are skipped.
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
startandendin 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.
Item types
By default vis-timeline draws an item as a range when end is set, otherwise as a box. To control this per note, point the view's item type field at a property whose value is box, point, or range:
views:
- type: timeline-view
name: moment of 2025
itemTypeField: note.timelineType
timelineType: point
- Values must be exactly
box,point, orrange(case-sensitive, same as vis-timeline); unknown values fall back to the vis default. - A
pointitem is drawn as a dot atstart;endandendLabelare ignored. - The property is not read unless item type field is configured, so an unrelated frontmatter
type:is harmless.
Custom styles
The plugin exposes three kinds of CSS hooks, which can be used separately or
together. All plugin-owned hooks live under the .timeline root class. Prefer
these classes over vis-timeline internals such as .vis-item: the plugin
guarantees its own classes, while vis-timeline's DOM may change between
versions.
[!warning] Upgrading from a version below 1.9 CSS snippets written for earlier versions need updating:
- Select item elements with
.timeline-iteminstead of.vis-item.- The wrapper around item content was renamed from
.timeline-itemto.timeline-item-content.- For example,
.vis-item:has(.timeline-item[data-status='done'])becomes.timeline-item:has(.timeline-item-content[data-status='done']).
- Item class: the note's
cssclasses(or the configured class name field) is written to the item'sclassNametogether withtimeline-item; target.timeline-item. - Item data attributes: the note's tags and frontmatter are injected into the
.timeline-item-contentwrapper inside the item content asdata-tagsanddata-{field}. - Background: the background item additionally gets
timeline-background,timeline-background-odd/timeline-background-even; its tags and frontmatter are written asdata-*attributes on that same element, plus a 1-baseddata-order.
Value rules: tags are space-separated in
data-tags; arrays are joined with spaces;Datevalues useYYYY-MM-DD; object values are skipped.
1. Item class
---
cssclasses:
- phase-bg
---
.timeline-item.phase-bg {
background-color: rgba(211, 211, 211, 0.45);
border-color: #d3d3d3;
}
2. Item data attributes
Item attributes live on the .timeline-item-content wrapper, so use :has()
on the item:
.timeline-item:has(.timeline-item-content[data-tags~='#projects']) {
border-width: 1px;
border-style: solid;
}
.timeline-item:has(.timeline-item-content[data-status='not started']) {
border-style: dashed;
}
3. Background
Background classes and attributes are on the background item itself, so
:has() is not needed:
.timeline-background-odd {
background-color: rgba(0, 0, 0, 0.06) !important;
}
.timeline-background-even {
background-color: rgba(0, 0, 0, 0.12) !important;
}
.timeline-background[data-phase='planning'] {
// custom styles
}
.timeline-background[data-order='3'] {
// custom styles
}
Backgrounds are sorted by start/end and numbered from 1 inside each swimlane;
a full-width background (no group) forms its own sequence. cssclasses is also
appended to the background's className.
Complete example
Assume a Base that renders notes tagged #phase as backgrounds:
filters:
or:
- file.tags.contains("moment")
- file.tags.contains("phase")
formulas:
isPhase: 'file.tags.contains("phase")'
views:
- type: timeline-view
name: roadmap
backgroundWhen: formula.isPhase
A regular event note:
---
start: 2025-01-05
end: 2025-01-09
content: Design review
status: not started
cssclasses:
- phase-bg
tags:
- projects
---
A phase background note:
---
start: 2025-01-01
end: 2025-03-31
content: Q1
phase: planning
tags:
- phase
---
Add a CSS snippet:
/* 1. Item class */
.timeline-item.phase-bg {
background-color: rgba(211, 211, 211, 0.45);
border-color: #d3d3d3;
}
/* 2. Item data attributes (on the .timeline-item-content wrapper) */
.timeline-item:has(.timeline-item-content[data-tags~='#projects']) {
border-width: 1px;
border-style: solid;
}
.timeline-item:has(.timeline-item-content[data-status='not started']) {
border-style: dashed;
}
/* 3. Background classes and attributes (on the background item itself) */
.timeline-background.timeline-background-odd {
background-color: rgba(0, 0, 0, 0.06);
}
.timeline-background.timeline-background-even {
background-color: rgba(0, 0, 0, 0.12);
}
.timeline-background[data-phase='planning'] {
border-color: #7aa2f7;
}
.timeline-background[data-order='1'] {
border-left-width: 3px;
}
The rendered DOM looks roughly like this:
<div class="timeline">
<!-- Regular event: class on .timeline-item, data-* on .timeline-item-content -->
<div class="vis-item vis-range phase-bg timeline-item">
<div class="vis-item-overflow">
<div class="vis-item-content">
<div
class="timeline-item-content"
data-tags="#projects"
data-status="not started"
>
…
</div>
</div>
</div>
</div>
<!-- Background: classes and data-* all on the background item -->
<div
class="vis-item vis-background timeline-background timeline-background-odd"
data-order="1"
data-tags="#phase"
data-phase="planning"
>
<div class="vis-item-overflow">
<div class="vis-item-content">Q1</div>
</div>
</div>
</div>
API
When you need to query data yourself (for example with DataviewJS), use the plugin's exposed api:
| Method | When to use |
|---|---|
api.render(containerEl, input, options?) |
You already have a generic data structure and want full control |
api.dv.render(containerEl, sources, options?) |
Pass Dataview page lists directly; the plugin maps fields and default item templates |
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.renderDataviewJS example at the cursor - Insert Dataview render template — inserts the
api.dv.renderDataviewJS example at the cursor
Previewing these blocks requires the Dataview plugin.
Tips
- Bases views and
api.render/api.dv.renderaccept calendar strings (YYYY,YYYY-MM,YYYY-MM-DD), integer numeric years, and JavaScriptDateobjects. Numbers represent years, not millisecond timestamps. - Missing months/days default to January/1:
"2025"→2025-01-01,"2025-03"→2025-03-01. Use text properties for partial dates or BCE dates in Bases. - Negative years are supported:
"-0044","-0044-03","-0044-03-15", or-44. Years follow JavaScript astronomical numbering:0000= 1 BCE,-0001= 2 BCE. Expanded ISO years are used internally. - Calendar dates use UTC midnight; Bases / Dataview normalize
Dateobjects to their UTC day. Invalid dates are rejected. The supported UTC boundaries are-271821-04-20and+275760-09-13(partial dates must also resolve within these bounds).
Installation
Three ways:
- (Recommended)Install from Obsidian Community Plugins, search
bases timeline viewto install - Manual install
- Download the latest release from GitHub Releases
- Create a folder
bases-timeline-viewunder.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 pluginto install - If it is not enabled automatically, enable
bases-timeline-viewin Settings → Community plugins
Other
- Thanks to vis-timeline and obsidian timeline