Dynamic Wallpaper

Set per-note background wallpapers in Obsidian using frontmatter properties. Wallpapers can be inherited from linked notes, browsed in a gallery, or randomized from any combination of inheritance tiers.

• 🖼️ Per-note wallpapers: Set a wallpaper frontmatter property linking to an image in your vault
• 🎰 Wallpaper pools: Set a wallpapers list instead and the plugin picks one at random each time you open the note — the pick then holds steady while you work in it
• 🔗 Wallpaper inheritance: Notes without a wallpaper can inherit from linked notes (via a specific frontmatter property, all frontmatter links, body links, or backlinks)
• 🎨 Wallpaper picker: Browse and select wallpapers from a visual gallery with thumbnail previews
• 🎲 Random wallpaper: Pick a random wallpaper from every image in your Wallpapers Directory, or from the set of wallpapers related to the active note
• 🗂️ Related wallpapers modal: See every wallpaper that could apply to the active note, grouped by which inheritance tier produced it
• 🧹 Thumbnail cache management: Clear or rebuild the cached thumbnails that power the picker and related-wallpapers modal
• 🌗 Overlay opacity: Adjust a color overlay per theme (light/dark) so text remains readable
• ↔️ Flip wallpaper: Horizontally flip the current wallpaper image
• 📌 Set wallpaper to note: Save the currently displayed wallpaper into the active note's frontmatter
• 🔒 Keep existing wallpaper: Optionally retain the wallpaper when navigating to notes without one

Desktop-only. This plugin uses Node.js fs APIs, which are not available on Obsidian Mobile.

Requires Obsidian 1.13.0+. The settings tab uses Obsidian's declarative settings API.

Commands

All commands are available from the Command Palette (Cmd/Ctrl + P).

• Choose Wallpaper: Open a visual gallery of every image in the Wallpapers Directory and click a thumbnail to apply it.
• Pick Random Wallpaper: Apply a random image from the Wallpapers Directory, skipping the one already on screen.
• View Related Wallpapers: Open a modal listing every wallpaper that could apply to the active note, grouped by inheritance tier.
• Pick Random Related Wallpaper: Apply a random wallpaper from the related set only, skipping the one already on screen.
• Increase Overlay Opacity: Raise the active theme's overlay opacity by 0.05.
• Decrease Overlay Opacity: Lower the active theme's overlay opacity by 0.05.
• Set Current Wallpaper to Note: Write the wallpaper currently on screen into the active note's frontmatter as a wiki link. If the note already has a non-empty wallpapers list, the wallpaper is appended to that pool instead (writing the singular property would have no effect, since the list takes priority).
• Refresh Wallpaper: Re-run the full wallpaper resolution pipeline for the active note, re-rolling any wallpapers pool.
• Clear Thumbnail Cache: Delete every file in the plugin's .cache directory.
• Rebuild Thumbnail Cache: Wipe the cache and regenerate a thumbnail for every image in the Wallpapers Directory.
• Flip Current Wallpaper (Horizontal): Mirror the current wallpaper image in place (overwrites the source file — no undo).

Related wallpapers & inheritance

Single wallpaper or a random pool

A note can name one wallpaper with the wallpaper property, or offer a pool with the wallpapers list property:

---
wallpaper: "[[sunset.jpg]]"
wallpapers:
  - "[[sunset.jpg]]"
  - "[[canyon.jpg]]"
  - "[[fog.jpg]]"
---

When a note has a non-empty wallpapers list, the plugin picks one entry at random and ignores that note's singular wallpaper property. The pick is re-rolled when you switch to the note — tab away and back and you may land on a different one — but it stays put while the note is active, so editing the note doesn't shuffle the background out from under you. The held wallpaper is kept as long as it's still in the pool; change the pool so it no longer qualifies and the next resolution draws again. Refresh Wallpaper forces a re-roll on demand. A note with only wallpaper behaves exactly as before.

Entries that don't resolve to an image in the vault are skipped rather than counted as a pick, so one typo'd link can't leave you with a blank background some of the time. If a note's list is empty or nothing in it resolves, resolution falls through to its wallpaper property and then on down the inheritance chain below.

Both property names are configurable in Settings, and the list property is honored at every inheritance tier — if [[Concerts]] defines a wallpapers list, every note inheriting from it gets a random pick from that pool.

Inheritance

A note doesn't have to set its own wallpaper. When the active note has no direct wallpaper frontmatter property, the plugin resolves one by following the note's links — so a wallpaper set on one note can cascade to everything connected to it.

Resolution order

The plugin walks these tiers in order and applies the first wallpaper it finds (first match wins):

1. Direct — a wallpaper set on the active note itself via the configured Wallpapers Property (random pick) or Wallpaper Property.
2. Inheritance Property — frontmatter outlinks of the property named in Inheritance Property (e.g., an areas: list).
3. Frontmatter Links — every other wiki link found anywhere in the frontmatter.
4. Body Links — wiki links in the note body, with the last link checked first.
5. Backlinks — notes that link to the active note. Each backlink is resolved through its own priority chain; the first backlink that yields a wallpaper wins.

Links under the wallpaper properties themselves are not followed as inheritance sources — they point at images, not at notes.

Tiers 2–5 can each be toggled off in Settings. A backlink of a backlink (transitive backlinks) is not followed — only direct backlinks of the active note are checked.

The "related" set

The related set is the full collection of wallpapers reachable through every enabled tier above, deduplicated by resolved file path. Two commands operate on it:

• View Related Wallpapers opens a modal listing every wallpaper in the set, grouped by the tier that produced it. Each card shows a thumbnail, the source note's name, and its tier. Click a card to apply that wallpaper; click the small ↗ source-name link to open the source note in a new leaf instead. Tiers with no wallpapers are hidden. Every entry of a wallpapers list is expanded into its own member of the set: a note contributing three wallpapers shows three cards, and counts as three candidates in the random draw (so it carries three times the weight of a note offering one).

• Pick Random Related Wallpaper applies a random wallpaper from this same set, skipping the one already on screen. Unlike Pick Random Wallpaper (which draws from the whole Wallpapers Directory), it never picks anything outside the related set.

Settings

Setting	Default	Description
Wallpaper Property	wallpaper	Frontmatter property name used to specify a single wallpaper
Wallpapers Property	wallpapers	Frontmatter property name holding a list of wallpapers; one entry is picked at random when the note is activated, then held while you work in it. Takes priority over Wallpaper Property
Wallpapers Directory	/	Vault folder containing wallpaper images
Keep existing wallpaper	true	Retain the wallpaper when navigating to a note without one
Inheritance Property	(empty)	Specific frontmatter property whose outlinks are checked for wallpapers (priority 2)
Inherit from all frontmatter links	true	Check every frontmatter outlink for a wallpaper (priority 3)
Inherit from body links	true	Check inline body links for a wallpaper — last link checked first (priority 4)
Inherit from backlinks	true	Check notes that link TO the active note for a wallpaper (priority 5, lowest)
Overlay Opacity (Light Mode)	0.8	Overlay opacity in light mode (0-1)
Overlay Opacity (Dark Mode)	0.6	Overlay opacity in dark mode (0-1)

For how the inheritance settings interact, see Related wallpapers & inheritance above.

Supported image formats

The wallpaper picker, related-wallpapers modal, thumbnail cache, and random-pick commands only recognize: png, jpg, jpeg, webp, gif, bmp, and svg. Files with other extensions are silently skipped.

Filesystem Disclosure

This plugin accesses the filesystem beyond what Obsidian's standard vault APIs provide:

• Thumbnail cache - Creates a .cache directory inside the plugin's own folder (<vault>/.obsidian/plugins/dynamic-wallpapers-plugin/.cache/) to store generated wallpaper thumbnails (480×270 cropped JPEGs). Thumbnails are generated from the original images via the browser's built-in canvas + createImageBitmap APIs — no external binary is required. No files outside the vault are created.
• Node.js fs APIs - Used for reading/writing thumbnail cache files. All file operations stay within the vault directory.

Contributing

See CONTRIBUTING.md for how to set up a local dev environment, including symlinking the build/ output into your vault and using the Hot-Reload plugin for fast iteration.

See AGENTS.md for project conventions and style guidelines.