Bases Timeline View

by xjiaxiang
5
4
3
2
1
Score: 52/100

Description

The Bases Timeline View plugin plots notes as timeline items using dates and content from frontmatter, with custom field mappings when vault properties use different names. It groups entries by note fields in Obsidian 1.10 or later and can render notes as regular items, time span backgrounds or vertical markers. Marker, background and item roles follow a fixed priority when conditions overlap. Timeline items support built in hover previews, CSS classes and data attributes for styling from tags or frontmatter. An exposed API accepts generic data structures, while its Dataview helper maps page lists into items, backgrounds and markers. Dates supplied as strings, Date values or numbers are normalised to YYYY-MM-DD and incomplete year or month values are completed into full dates.

Reviews

No reviews yet.

Stats

26
stars
7,246
downloads
0
forks
47
days
8
days
8
days
12
total PRs
0
open PRs
0
closed PRs
12
merged PRs
1
total issues
0
open issues
1
closed issues
50
commits

Latest Version

9 days ago

Changelog

1.9.0 (2026-11-10)

Features

  • enhance timeline background rendering with data attributes and sorting (e1a469a)

README file from

Github

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: example

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-01
    • YYYY-MM, e.g. 2025-03 → 2025-03-01
    • YYYY-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-5 are not supported); 2025/03/15, natural-language dates, and impossible dates such as 2025-02-30 are 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: 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-example

  • 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.

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, or range (case-sensitive, same as vis-timeline); unknown values fall back to the vis default.
  • A point item is drawn as a dot at start; end and endLabel are 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-item instead of .vis-item.
  • The wrapper around item content was renamed from .timeline-item to .timeline-item-content.
  • For example, .vis-item:has(.timeline-item[data-status='done']) becomes .timeline-item:has(.timeline-item-content[data-status='done']).
  1. Item class: the note's cssclasses (or the configured class name field) is written to the item's className together with timeline-item; target .timeline-item.
  2. Item data attributes: the note's tags and frontmatter are injected into the .timeline-item-content wrapper inside the item content as data-tags and data-{field}.
  3. Background: the background item additionally gets timeline-background, timeline-background-odd / timeline-background-even; its tags and frontmatter are written as data-* attributes on that same element, plus a 1-based data-order.

Value rules: tags are space-separated in data-tags; arrays are joined with spaces; Date values use YYYY-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 });
}
```

api-render-example

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.render / api.dv.render accept calendar strings (YYYY, YYYY-MM, YYYY-MM-DD), integer numeric years, and JavaScript Date objects. 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 Date objects to their UTC day. Invalid dates are rejected. The supported UTC boundaries are -271821-04-20 and +275760-09-13 (partial dates must also resolve within these bounds).

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

Similar Plugins

info
• Similar plugins are suggested based on the common tags between the plugins.
Siteswap
5 years ago by Tim Dresser
Release Timeline
4 years ago by cakechaser
Chronology
4 years ago by Gabriele Cannata
Vega Visualizations
4 years ago by Justin Kim
Create Vega and Vega-Lite visualizations in https://obsidian.md/.
Tasks Calendar Wrapper
4 years ago by zhuwenq
This plugin currently provides a timeline view to display your tasks from your obsidian valut, with customizable filters and renderring options.
Timeline View
3 years ago by b.camphart
Obsidian plugin for viewing your notes linearly based on a given property
Barcode Generator
3 years ago by noxonad
A barcode generator for obsidian.
Timeline Schedule
3 years ago by Evan Bonsignori
Inline timelines generated from human-readable time strings, e.g. 'Walk dog (30min)' in a ```schedule codeblock.
Markline
3 years ago by 闲耘
Markline: Markdown timeline view in Obsidian.
MemoryLane
3 years ago by BangCa
Relive and celebrate your life's milestones on a personal, interactive timeline. A nostalgic journey through your history with anniversary reminders and cherished memories.
Focus Tracker
2 years ago by Jeet Sukumaran
Charts View
5 years ago by caronchen
Data visualization solution in Obsidian, support plots and graphs.
Timeline
5 years ago by George Butco
Obisdian.md plugin for creating timelines
Plotly
5 years ago by Dmitriy Shulha
Obsidian plugin to embed Plotly charts into markdown notes.
Markdown Timeline
2 years ago by Jiaheng Zhang
An Obsidian plugin to record the events in a Flashback timeline
Chronos Timeline
2 years ago by Claire Froelich
Render interactive timelines in your Obsidian notes from simple Markdown.
Easy Timeline
2 years ago by Romeliun
The Easy Timeline plugin for Obsidian allows you to create timelines easily.
Recent Notes
2 years ago by Kamil Rudnicki
Recent Notes Plugin for Obsidian
Sankey
2 years ago by Finn Romaneessen
An Obsidian plugin to create sankey diagrams
SQLSeal Charts
2 years ago by hypersphere
Charting extension for SQLSeal Obsidian Plugin. Visualise your data!
Content Cards
2 years ago by leo
Insert content cards in Markdown, such as timeline, highlightblock, target card, book information card, music information card, movie information card, photoes ablum, business card, content subfield, countdown, SWOT,BCG.
Generate Timeline
2 years ago by Shanshuimei
An obsidian plugin to generate timelines from tags, folders, files or metadata automatically. 根据标签,文件夹,文件或者属性自动生成时间轴的插件。
QueryDash
2 years ago by lwx
aDHL
2 years ago by tine-schreibt
The Dynamic Highlights Plugin, but with hotkeys, more options and sorting; works well with Highlightr.
Reactive Notes
2 years ago by Elias Noesis
Byte Field Diagrams
2 years ago by natri0
Byte-field diagrams for Obsidian.
Vertical Timeline List
2 years ago by Jalad
Utilizes task lists to create a timeline... or something like a timeline.
Inboxer
2 years ago by Eoin Hurrell
Obsidian plugin to add an inbox to notes
Markwhen File Sync
a year ago by rouvenjahnke
Synchronize properties from your Obsidian notes with a Markwhen timeline file.
Timelive
a year ago by aNNiMON
Turn a list of dates into a timeline
Alpha Bullet
a year ago by Mara-Li
Obsidian plugin that sorts bulleted lists alphabetically.
Timeline Canvas Creator
a year ago by chris-codes1
Quickly create timeline structured canvases in Obsidian.
Storyteller Suite
a year ago by Maws
Datacore
a year ago by Michael Brenan
Work-in-progress successor to Dataview with a focus on UX and speed.
Maps
a year ago by Obsidian
Map layout for Obsidian Bases. Display your notes as an interactive map view.
Kanban Bases View
8 months ago by I. Welch Canavan
A kanban-style drag-and-drop custom view for Obsidian Bases that allows you to organize your notes into columns based on any property.
Calendar Bases
8 months ago by Edrick Leong
Feed Bases
6 months ago by edrickleong
Bases Charts
6 months ago by Moritz Jung
Day Planner OG
6 months ago by ebullient
An Obsidian plugin for day planning and managing pomodoro timers from a markdown task list.
Timelines (Revamped)
6 months ago by seanlowe
Create a timeline view of all notes with the specified combination of tags
Base Board
6 months ago by mderazon
Kanban Plugin For Obsidian
Life Tracker
6 months ago by Sébastien Dubois
Capture and visualize the data that matters in your life
April Automatic Timelines
5 months ago by april-gras
Simple timeline generator plugin for story tellers using obsidian
Charted Roots
5 months ago by John Banister
Professional genealogical tools for Obsidian. Interactive family charts, geographic maps, PDF reports, GEDCOM/Gramps import-export, evidence tracking, and fictional calendar support. Built for genealogists, historians, and worldbuilders.
TaskNotes
5 months ago by callumalpass
Task and time-tracking management with calendar integration for Obsidian
Gantt Calendar
4 months ago by Sugar
obsidian-gantt-calendar
StoryLine
4 months ago by Jan Sandström
StoryLine transforms your Obsidian vault into a complete book planning and writing tool. Organize scenes, build characters, manage locations, track plotlines, and monitor your progress, all inside Obsidian.
ReverySky Map
4 months ago by MoonSkorch Studio
Obsidian plugin rendering the vault graph as an interactive 3D star map with Unity WebGL
Bases Paginator
4 months ago by sean2077
A plugin for Obsidian that adds a paginated table view with column filtering capabilities to Obsidian Bases.
Bases Toolbox
4 months ago by Grub Basket
Adds Quality of Life features to Obsidian Bases
Power Bases
3 months ago by Power Plugins
Add board, calendar, timeline, chart, gallery, and table views to Bases, with inline editing, colors, rollups, field types, formulas, and CSV import.
Journal View
3 months ago by RUverse
A journal view for Obsidian
Canvas Bases
3 months ago by callumalpass
Canvas-style layouts and JSON Canvas materialization for Obsidian Bases.
Gantt this
3 months ago by Altarok
Obsidian plugin showing multiple TTRPG calendars at once in one gantt chart.
Link Structure
3 months ago by Dmitry Fert
Obsidian plugin that adds a Structure view for Bases, displaying notes as a hierarchical tree based on the up property. Supports drag-and-drop reorganization with automatic link updates, multi-select, and Templater integration.
Xyls Starmap
3 months ago by xylhazlhztarr
A small little plugin for Obsidian MD to create interactive star system maps and planet-side views inside the note-taking app.
Abele
3 months ago by dudaanton
An Obsidian plugin that adds a lot of functionality I personally find missing.
Base Source Editor
2 months ago by fronglemog
Edit the YAML source of a Base without leaving Obsidian.
Split Groups
2 months ago by Fuad Laguda
Obsidian Bases view that puts a note in every group its list property names
Projects Plus
2 months ago by Pavel
Projects Plus turns a folder of notes into a managed project: you see all tasks on a kanban board, all events on a calendar, all cards in a gallery — all without export, without cloud, right in your vault.
Mappy
2 months ago by hiroyaiizuka
An Obsidian plugin to view and edit Markdown notes as linked, illustrated mind maps.
Routine Timeline
a month ago by Arsalan Amin
The Routine Timeline plugin is built and sent as main.js, manifest.json and styles.css. It type-checks and bundles cleanly, but I couldn't run it inside Obsidian, so test it before relying on it.
Prism
a month ago by floorianmb
Prism: sandboxed, themed, interactive visualizations in Obsidian notes
Home Cards
a month ago by ttangents
Give your vault a homepage: a start page or dashboard of note cards from recent notes, properties, tags, links and Bases, with pins, project boards and pages for any folder or tag.
Cool Bases
a month ago by pattgue
Design cool card views for Obsidian Bases.
Masonry
a month ago by Mario Miletta
A visual masonry browser for Obsidian notes and filtered Bases.
Horizon
a month ago by Mario Miletta
Horizon — calendar for your Obsidian vault: daily and periodic notes, tasks, and dated notes in one place.
Note Player
24 days ago by xia-ataraxia
Obsidian plugin that plays note-backed playlists with YouTube (via yt-dlp), cached audio, and local files.
Just Simple Planner
19 days ago by David Hurt
A local visual planner for Obsidian: Markdown notes on a continuous timeline, connected threads, compact previews, tasks and notebook view.