12 KiB
Icons and banners from properties (roadmap item 16)
Part of specs/plugins-parity/. Replaces the community plugins Iconize (2.27M downloads),
Banners and the icon half of Pretty Properties. Research (2026-10-21):
- Banners (github.com/noatpad/obsidian-banners README): frontmatter keys
banner(URL or internal image link, quoted),banner_x,banner_y(0 to 1, centre of the visible window),banner_lock,banner_icon(emoji); solid and gradient banner styles; banners also in embeds and page previews; adjustable heights; drag to reposition. - Iconize (github.com/FlorianWoelki/obsidian-iconize, listing on community.obsidian.md): icons before file and folder names, icons in notes and above titles, icon packs plus custom SVG, icons in tabs, custom rules, frontmatter integration, per-icon colour. Maintenance has stopped upstream; forks (GlyphIt) and Iconic (rule-based by name, extension, parent folder, tags, properties) continue it.
- The exact Iconize frontmatter spelling (
icon,iconColor) was not confirmable from fetched pages; the spec adoptsiconandiconColoras the contract and tests with real notes first (Open question Q1).
Problem
Users who tag notes with icon: LiRocket or banner: "[[cover.jpg]]" see none of it. The Explorer shows
one generic file icon for every note, tabs likewise, and a note has no header image. The Bases Cards view
already shows an image property as a cover (views/base_view/layouts/cover.rs) but nothing else uses
image properties.
Goal
Two properties drive the look of a note, everywhere, with no extra file:
icon(and optionaliconColor): shown in the Explorer row, the tab, the quick switcher and search rows, the Bases name column, and above the title in the note view.banner(andbanner_y): a header image at the top of the note view and on hover cards. Folders take their icon from their folder note (Folder/Folder.mdor the configured folder-note name). Setting them is a context-menu action ("Set icon", "Set banner") that writes the property through the existing property commands. Properties are the single source of truth; Obsidian users keep their data.
Non-Goals (v1)
- Custom icon packs download (Iconize packs from the network): offline only.
- Rules ("all notes in
Projects/get icon X"): Feature ideas. - Remote banner URLs: the network policy of the roadmap forbids fetching without its own settings switch;
banner: https://...shows a placeholder card with an "enable" notice, no fetch (same pattern as Maps). - Icons inside note text (
:LiRocket:), banners in embeds and page previews, gradient banner style. - Animated icons for notes (the Lottie helpers stay for controls).
Design decisions
D1 - Property contract
| Key | Value | Meaning |
|---|---|---|
icon |
rocket, lucide-rocket, LiRocket (Lucide), an emoji (🚀), or a wikilink/path to an .svg/.png in the vault ([[icons/rocket.svg]]) |
the icon |
iconColor |
#rrggbb, #rgb, a theme token name (accent, danger, success) |
tint for Lucide/SVG icons (emoji and PNG keep their colours) |
banner |
wikilink [[cover.jpg]], ![[cover.jpg]], vault path, or https:// URL (placeholder only) |
header image |
banner_y |
number 0..1 (default 0.5) | vertical focus of the crop, 0 top, 1 bottom |
banner_x |
number 0..1 (default 0.5) | horizontal focus |
banner_icon |
emoji | used as icon when icon is absent (Banners compatibility) |
Invalid values are ignored (no icon, no banner), never an error shown on every frame; a Properties-view
warning chip is enough (Feature ideas). banner_y clamps ONLY for painting (input is hostile but a
numeric focus, not a size); an out-of-range value is displayed as the nearest edge and flagged in the
properties view.
D2 - Pure resolver in the index crate
crates/index/src/decor.rs (L1, pure):
pub enum IconRef { Lucide(String), Emoji(String), File(String) /* vault link target as written */ }
pub struct Decor { pub icon: Option<IconRef>, pub color: Option<ColorRef>, pub banner: Option<BannerRef> }
pub enum ColorRef { Rgb(u8, u8, u8), Token(String) }
pub struct BannerRef { pub target: BannerTarget, pub x: f32, pub y: f32 }
pub enum BannerTarget { File(String), Url(String) }
pub fn decor_from_props(props: &[(String, PropValue)]) -> Decor;
pub fn parse_icon(raw: &str) -> Option<IconRef>;
Rules: Lucide spellings LiRocket, lucide-rocket, rocket, Rocket normalise to kebab case
rocket (LiArrowRight -> arrow-right); an emoji is one extended grapheme cluster that is not ASCII
alphanumeric (use the scanner already used for emoji detection in the editor, grep is_emoji before
writing one); a value ending .svg/.png/.webp, or wrapped in [[ ]], is File. Limits: value 1 KiB.
The index already keeps all properties per note (Bases task 9), so no index change: Decor is derived from
Index::note_props(path) on demand and cached by the engine (D3).
D3 - Engine
crates/engine/src/decor/ (mod.rs, commands.rs, resolve.rs):
| id | params | result | writes |
|---|---|---|---|
decor.list |
{paths?: [..], prefix?: ".."} |
{items:{path:{icon?,color?,banner?:{path,x,y}}}, generation} |
no |
decor.set |
{path, icon?, color?, banner?, banner_y?} (null removes) |
{path} |
yes |
decor.list with no paths returns only notes that HAVE a decoration (fast: iterate the index once, cached
per index generation, 15 000 notes < 20 ms warm); folders resolve through the folder note. banner links
are resolved with the same link resolution as wiki links, so [[cover.jpg]] finds
assets/cover.jpg. decor.set reuses crate::vault::properties::set (one undoable edit when the note is
open, note.property_set semantics, .obsidian/types.json types honoured). Add ids to
ai/assistant_gate.rs (list READ; set WRITE; the icon catalogue is UI-side, so there is no decor.icons) and CORE_IDS.
Settings [appearance.decor]: icons_enabled (true), banners_enabled (true), banner_height (px at
scale 1, default 180, range 80..400, validated and rejected out of range), property_icon (icon),
property_color (iconColor), property_banner (banner): the property names are configurable because
vaults differ (cover is common).
D4 - UI
crates/ui-egui/src/design/note_icon.rs:paint(ui, &IconRef, rect, tint, tokens)for Lucide (staticicons::paint), Emoji (egui text, monochrome emoji font: see risk), File (SVG/PNG through the image loader behind a bounded texture cache of 256 entries, decoded off the UI thread).- Lucide catalogue: the app embeds 91 icons today (
design/icons.rs). Add a curated set of about 250 common Lucide icons underassets/icons/lucide/listed indesign/icon_catalogue.rs(a&[(&str, &[u8])]); names outside the catalogue render the generic file icon and the picker never offers them. - Hook points (each a small edit, listed per task): Explorer row
panels/tree.rs:~672(replaces thefile-textslot when a decor icon exists; folders use the folder-note icon), tab iconwidgets/tabs/paint.rs:35,~204, note title areaviews/note_view/(icon above the title, size 40), quick switcher and search rows (task 7), Bases name columnviews/base_view/table/cell.rs. - Banner:
views/note_view/banner.rspaints the image full width at the top of the document, cropped withobject-fit: coverand thex/yfocus, height from settings, scrolls away with the note, rounded bottom corners on thesurfacecard. Image decode reusesviews/base_view/layouts/cover.rs(read it first: it already loads and caches vault images for Cards). A broken link shows no banner and a hover tooltip on the properties row, nothing on the page. - Picker: a popover (
Dropdown/Modallibrary widgets) with tabs Icons (search the catalogue, grid, colour swatches from theme tokens), Emoji (a text field plus the OS picker hint), File (pick an image from the vault tree). Entry points: Explorer context menu "Set icon...", note menu "Set banner...", hover on the note icon, palette "Icon: Set / Remove". Everything callsdecor.set.
D5 - Performance and safety
Explorer paints thousands of rows: decorations come from ONE decor.list snapshot held in egui memory and
refreshed on index generation change; no per-row engine call. Texture cache bounded; decode of one image
capped at 8 MiB file / 4096 px (reject bigger, no downscale-on-read hack: show a placeholder). SVG icons
from the vault are rendered with the existing craft-ui SVG path (no scripts run; reject files over 64 KiB).
No network. Never write outside the property of the note.
Acceptance criteria
- A note with
icon: LiRocketandiconColor: "#ff8800"shows a rocket tinted orange in the Explorer, its tab, and above its title; removing the property removes it on the next frame. icon: 🚀shows the emoji;icon: "[[icons/star.svg]]"shows the vault SVG tinted byiconColor.banner: "[[cover.jpg]]"withbanner_y: 0.2shows the image cropped at 180 px height, focus near the top; a missing file shows no banner and no panic.banner: https://example.com/a.pngmakes ZERO network requests (stub server count) and shows the placeholder text.- A folder with a folder note carrying
iconshows that icon on the folder row; without a folder note it keeps the folder icon. - "Set icon..." on a note writes
icon:into the frontmatter as ONE undoable edit, body byte-identical. decor.liston a 15 000-note vault, 2 000 decorated: < 20 ms warm (ignored perf test); Explorer scroll does not call the engine per row (counter test).- Properties keep working when a vault already uses Iconize/Banners keys; unknown spellings change nothing.
- Theme change retints Lucide icons that use a token colour.
Open questions
- Q1: confirm the Iconize frontmatter key spelling with a real vault note (
icon,iconColor) and add it to the fixture tests. Also confirm if Iconize stores folder icons indata.json, not in the notes: then an optional importer (reads.obsidian/plugins/obsidian-icon-folder/data.json) goes to Feature ideas. - Q2: emoji rendering: egui ships a monochrome emoji font. Acceptable for v1? (Color emoji = Twemoji pack, Feature ideas.)
- Q3: bundle ~250 Lucide icons (about 250 KB) or the full set (1.5k, about 1.5 MB)?
Feature ideas (researched, ranked by value)
- Rules by folder / tag / property (Iconize custom rules, Iconic): a
[appearance.decor.rules]list{match: folder|tag|property, value, icon, color}, evaluated once per index generation; makes a wholeProjects/tree pretty without editing 300 notes. Highest value after the properties themselves. - Cover image for Bases Cards from
banner: Cards view already supports a cover property; default it to the configured banner key, so Bases and notes share one image. - Folder icons without a folder note through a
.notescraft/icons.tomlmap (path -> icon), written by "Set icon" on a folder (a folder-note-less folder). Cheap, covers the common case of plain folders. - Color emoji with a bundled Twemoji/Noto PNG sheet subset (about 3 000 glyphs, 1 MB): fixes Q2.
- Banner drag to reposition (Banners drag modifier): drag the image, release writes
banner_y/banner_x(rounded to 2 decimals); lock withbanner_lock: true. - Banners in hover cards and embeds (
![[note]]shows the banner small), and a card-size banner in the quick switcher preview. - Import Iconize/Banners settings: read
.obsidian/plugins/obsidian-icon-folder/data.json(folder and file icons stored outside notes) and offer to write them as properties; one-shot migration command. - Gradient/solid banner style (no image):
banner: "#336699"or a two-stop gradient string. - Properties-view chips: an icon preview next to the
iconrow and a warning chip for invalid values (banner_yout of range, unknown Lucide name). - Icon in graph nodes and calendar events from the same
decor.listsnapshot.