Advanced Pomodoro Timer for Obsidian Dataview

[MATrsx]

Advanced Pomodoro Timer for Obsidian Dataview

A beautiful, feature-rich Pomodoro timer built entirely with Dataview JS that transforms your Obsidian workspace into a productivity powerhouse. Track your focus sessions, customize themes, and stay motivated with visual progress tracking—all without leaving your notes.

---

Overview

This Pomodoro timer brings the popular time management technique directly into Obsidian with a sleek, modern interface. Unlike basic timers, this implementation offers:

• Seven Beautiful Themes - From minimalist to vibrant
• Customizable Sound Notifications - Four distinct alert styles
• Comprehensive Statistics - Track daily and total progress
• Smart Auto-start - Seamless workflow automation
• Flexible Storage - Choose between frontmatter or browser storage
• Visual Progress Tracking - See your daily goals at a glance
• Fully Responsive - Works on desktop, tablet, and mobile

---

Features

Core Features

Feature	Description
Work/Break Modes	Three distinct modes: Pomodoro (25min), Short Break (5min), Long Break (15min)
Timer Controls	Start, Pause, Reset with intuitive controls
Session Tracking	Automatic logging of all completed sessions
Daily Statistics	Real-time tracking of today’s pomodoros and total work time
Progress Visualization	Circular timer display with animated progress bar
Completion Alerts	Browser notifications + in-app notices

Advanced Features

Feature	Description
Auto-start Sessions	Automatically begin breaks after work or work after breaks
Long Break Interval	Configurable long break scheduling (default: every 4 pomodoros)
Daily Goal Tracking	Set and visualize daily pomodoro targets
Web Audio API Sounds	Four customizable notification sounds with volume control
Theme System	Seven pre-built color schemes with instant switching
Dual Storage Options	Save data in frontmatter (file-specific) or localStorage (global)
Browser Tab Updates	See remaining time in your browser tab title
Data Migration	Seamlessly switch between storage methods

UI/UX Features

Feature	Description
Animated Transitions	Smooth animations for mode switches and completions
Responsive Design	Mobile-optimized layout (320px+)
Dark Mode Support	Automatic theme adaptation
Accessibility	Keyboard navigation and screen reader support
Visual Feedback	Pulsing animations during active sessions
Celebration Effects	Fun animations on session completion
Icon Support	Integration with Obsidian Icon Folder plugin (optional)

---

Installation

Prerequisites

• Dataview Plugin installed and JavaScript queries enabled
• Iconize (optional, to display Lucide icons instead of Emojis)

Step-by-Step Installation

Install Required Plugins

Settings → Community Plugins → Browse

Search for and install:

• Dataview
• Iconize (optional)

Add the Code

In your vault, add a new folder called pomodoro inside your Dataview userscripts folder (e.g. Scripts/Dataview/pomodoro) and 2 new files:

📁Vault
├───📁.obsidian
└───📁Scripts
    └───📁Dataview
        └───📁pomodoro
             ├───📄view.css
             └───📄view.js

https://gist.github.com/MATrsx/851fb61a1165c1c114d8c1d219763f87

Create the Timer Note

1. Create a new note (e.g., Pomodoro Timer.md)
2. Add the following DataviewJS Codeblock

```dataviewjs
await dv.view('pomodoro')
```

Initial Setup (Optional)

Add frontmatter to customize initial settings:

---
pomodoroData:
  settings:
    workDuration: 25
    shortBreakDuration: 5
    longBreakDuration: 15
    theme: "default"
    soundType: "bell"
    soundVolume: 50
---

Launch

Open the note in Reading View or Live Preview to see your timer!

---

Basic Usage

Quick Start Guide

1. Select Mode: Click “Pomodoro” for work time
2. Start Timer: Hit the Start button
3. Focus: Work until the timer completes
4. Take a Break: Timer auto-switches to Short Break
5. Repeat: Continue your productive cycle!

Mode Selection

Mode	Duration	Purpose	Color
Pomodoro	25 minutes	Focused work session	Red gradient
Short Break	5 minutes	Quick rest between pomodoros	Blue gradient
Long Break	15 minutes	Extended rest after 4 pomodoros	Purple gradient

---

Configuration Options

Timer Settings

Setting	Default	Description
Work Duration	25 min	Length of work sessions
Short Break	5 min	Length of short breaks
Long Break	15 min	Length of long breaks
Long Break Interval	4	Pomodoros before long break
Daily Goal	8	Target pomodoros per day

Auto-start Options

Setting	Default	Description
Auto-start Breaks	Off	Automatically begin breaks after work sessions
Auto-start Work	Off	Automatically begin work after break sessions

Tip: Enable auto-start for a truly hands-off Pomodoro experience. The timer will give you a 3-second heads-up before starting.

Sound Notifications

Sound Type	Character	Best For
Bell	Gentle, melodic	Quiet environments
Chime	Musical, uplifting	General use
Notification	Quick, attention-grabbing	Busy workspaces
Digital	Sharp, modern	Tech enthusiasts

Volume Range: 0-100% (adjustable in 1% increments)

Theme Gallery

Theme	Vibe	Work Color	Break Colors	Best For
Default	Classic	Red	Blue/Purple	General productivity
Forest	Natural	Green	Teal/Blue	Calm focus
Sunset	Warm	Red-Orange	Orange/Purple	Creative work
Ocean	Cool	Blue	Teal/Dark Blue	Deep concentration
Pastel	Soft	Coral	Mint/Lavender	Gentle on eyes
Space	Dark	Deep Purple	Purple/Cyan	Night owls
Minimal	Simple	Charcoal	Blue/Pink	Distraction-free

Storage Options

Storage Type	Pros	Cons	Use Case
Frontmatter	• File-specific data • Version control friendly • Syncs with vault	• Separate data per file • Requires file write permissions	Project-specific tracking
Browser Storage	• Global across all files • No file modifications • Faster access	• Not synced • Browser-dependent • Can be cleared	Personal desktop use

---

Theme Showcase

Visual Comparison

Each theme transforms the entire timer interface:

Default Theme	Forest Theme	Ocean Theme	Pastell Theme

How to Change Themes

1. Click the Settings button
2. Scroll to “ Theme” section
3. Click any color preview box
4. Theme applies instantly!
5. Hit “Save” to keep your choice

---

Best Practices

Do’s

Practice	Benefit
Set a realistic daily goal	Start with 6-8 pomodoros, adjust based on your rhythm and workload
Take breaks seriously	Stand, stretch, hydrate—breaks are for recovery
Enable browser notifications	Never miss a session completion
Review your stats regularly	Track patterns in your productivity
Choose a comfortable theme	Your eyes will thank you after hours of work
Choose storage based on use	Frontmatter for project work, localStorage for personal tracking

Don’ts

Pitfall	Solution
Skipping breaks	Breaks are essential for sustained focus—honor them!
Checking phone during pomodoros	Close distractions, use breaks for quick checks
Setting work duration too long	25 minutes is scientifically optimal for focus
Unrealistic daily goals	Quality > Quantity. 8 focused pomodoros beats 15 distracted ones
Muting all notifications	You might work through breaks without audio/visual cues
Switching storage frequently	Pick one and stick with it for consistent tracking

---

Advanced Usage

Custom Workflows

The Deep Work Setup

Settings:
- Work Duration: 50 minutes
- Short Break: 10 minutes
- Long Break: 30 minutes
- Auto-start Breaks: ON
- Auto-start Work: OFF (manual restart for intentionality)

The Sprint Method

Settings:
- Work Duration: 15 minutes
- Short Break: 3 minutes
- Long Break: 15 minutes
- Long Break Interval: 3
- Auto-start Everything: ON (maximum momentum)

The Flexible Schedule

Settings:
- Work Duration: 25 minutes (standard)
- Short Break: 5 minutes
- Long Break: 20 minutes
- Storage: Frontmatter (track per project)

---

Understanding Statistics

Stats Dashboard Explained

Stat	Calculation	Updates
Today	Completed work pomodoros since midnight	After each work session
Total	All-time completed work pomodoros	Cumulative, never resets
Time	Total work hours (work sessions only)	Excludes break time

Progress Indicators

Daily Dots

• Filled dots: Completed pomodoros today
• Empty dots: Remaining to reach daily goal
• Updates automatically after each work session

Session Progress Bar

• Shows current session progress
• Animates smoothly as time passes
• Resets at the start of each new session

---

Interface Gallery

Main Timer View

The timer features a large, easy-to-read circular display with the current mode clearly indicated:

The circle color changes with each mode. These are the colors for the default theme:

• Red during work
• Blue during short breaks
• Purple during long breaks

Settings Modal

The settings panel is organized into clear sections:

---

Data Privacy & Security

What Gets Stored

Frontmatter Storage

pomodoroData:
  sessions:
    - mode: "work"
      duration: 25
      completed: true
      date: "2025-11-04T10:30:00.000Z"
  stats:
    completedPomodoros: 145
    totalWorkTime: 3625
  settings: { ... }

Browser Storage (localStorage)

Same structure, stored as JSON in pomodoroTimerData key

Privacy Notes

Completely Local: All data stays on your device
No Analytics: Zero tracking or external connections
No Account Required: Works entirely offline

---

Credits & Acknowledgments

Built with:

• Obsidian: The extensible knowledge base
• Dataview: Powering the JavaScript functionality
• Web Audio API: For notification sounds

The Pomodoro Technique® is a time management method developed by Francesco Cirillo in the late 1980s. This timer is an independent implementation and is not affiliated with or endorsed by Francesco Cirillo or Cirillo Consulting GmbH.

---

License

This code is provided as-is for personal use in Obsidian. Feel free to:

• Use in your personal vault
• Modify for your needs
• Share with attribution

---

Questions? Feedback? Share your thoughts and feedback below!