Enhanced Folders
Add custom images, descriptions, and inline rename to Spotify playlist folders — the metadata Spotify never exposed natively.

Features
Section titled “Features”- Custom image per folder — replaces the default folder icon in the sidebar with any image you upload (auto-cropped to a 354px JPEG, ~150 KB)
- Custom description — free-text per folder, shown as a hover tooltip on the sidebar row
- Inline rename — change the folder name from the same dialog (uses
Spicetify.Platform.RootlistAPI.renameFolder, no need to open Spotify’s separate Rename dialog) - Folders filter chip — a Folders chip in the sidebar filter bar (next to Playlists, Albums, …) that swaps the library list for a folders-only view; click a folder to expand its playlists inline. Click any native chip to return to Spotify’s list
- One context-menu entry — right-click any folder → Edit folder details; image picker + description + name fields in one modal
- Profile-dropdown settings panel — Export / Import folder data as JSON, clean up stale entries, force re-render
- Theme-aware — uses Spice CSS variables so the UI matches the active Spicetify theme (parity with Album Length, Listening List, Enhanced Pins)
- Robust against Spotify UI churn — multi-strategy URI lookup and selector fallbacks; debounced
MutationObserverso sidebar re-renders don’t thrash
How It Works
Section titled “How It Works”Spotify treats playlist folders as client-side rootlist nodes; they have no first-class metadata API and no native edit dialog. This extension:
- Enumerates folders via
Spicetify.Platform.RootlistAPI.getContents()(the modern Platform API — the legacysp://core-playlist/v1/rootlistCosmos endpoint no longer resolves in current Spotify) - Registers an
Edit folder detailsitem in the folder context menu viaSpicetify.ContextMenu - Persists per-folder image (base64 JPEG, square-cropped to ~354px) and description in
Spicetify.LocalStorage, keyed by folder ID - Decorates the sidebar by finding each folder row via its
#listrow-title-<uri>element, then overlaying the user’s image inside the existing artwork container (forcesposition: relativeon the slot at decoration time so the absolutely-positioned image stays bounded) - Renames via the protobuf-backed
RootlistAPI.renameFolder({uri}, name)modification, which dispatches a rootlist-changed event that Spotify’s React tree picks up automatically — no manual refresh needed
Installation
Section titled “Installation”Requires Spicetify, installed and applied at least once, and the Spotify desktop app (the web player isn’t supported). The Marketplace route also needs the Spicetify Marketplace custom app.
From Spicetify Marketplace
Section titled “From Spicetify Marketplace”- In Spotify, open Marketplace (the shopping-cart icon at the top left) and stay on the Extensions tab.
- Search for
Enhanced Folders. If it doesn’t show up, click Load more (» at the bottom of the list) until it does. Marketplace loads extensions in batches and only searches the ones it has loaded. - Hover the Enhanced Folders card, click its download button, then click Reload now.
Manually
Section titled “Manually”-
Download
enhanced-folders.js(right-click → Save link as…) into your SpicetifyExtensionsfolder:- Windows:
%APPDATA%\spicetify\Extensions - macOS / Linux:
~/.config/spicetify/Extensions
- Windows:
-
Enable it and apply:
Terminal window spicetify config extensions enhanced-folders.jsspicetify apply
To confirm it loaded, open DevTools (Ctrl+Shift+J, requires spicetify enable-devtools) and look for [Enhanced Folders] Booted. in the console.
Right-click any playlist folder in the sidebar → Edit folder details → upload an image, type a description, optionally rename, save.

| Action | Where |
|---|---|
| Edit folder image / description / name | Folder right-click → Edit folder details |
| Export folder data as JSON | Profile dropdown (top-right avatar) → Enhanced Folders → Export |
| Import folder data | Profile dropdown → Enhanced Folders → Import (Merge or Replace) |
| Clean up entries for deleted folders | Profile dropdown → Enhanced Folders → Clean up deleted folders |
| Force a sidebar re-render | Profile dropdown → Enhanced Folders → Re-render sidebar |
Backup & Sync
Section titled “Backup & Sync”Folder IDs are local to each Spicetify install — they don’t sync across devices via Spotify. To move customizations between machines, Export to JSON on the source machine and Import on the target.
The export format is a single JSON document keyed by folder ID:
{ "schemaVersion": 1, "folders": { "bcc91019a404b0f3": { "image": "data:image/jpeg;base64,/9j/...", "description": "Workout playlists", "updatedAt": 1748131200000 } }}Troubleshooting
Section titled “Troubleshooting”- Image isn’t appearing in the sidebar — open DevTools (
Ctrl+Shift+J). If you see[Enhanced Folders] no rows matched for N stored folder(s), the parent folder might be collapsed — expand it. If decoration consistently fails after a Spotify update, file an issue with your Spotify version and a snippet of a folder row’s HTML. - Rename toast says “API unavailable” — the
RootlistAPI.renameFoldersignature changed in your Spotify version. File an issue with your Spotify version; image/description save will still work. - Customizations missing on another device — expected. Folder IDs are local. Use Export / Import.
- Lost data after Spotify reinstall — same reason. Back up via Export regularly.
Compatibility
Section titled “Compatibility”Tested against Spotify desktop on Windows with the YourLibraryX sidebar (list view), including Spotify 1.3.4.258. That build dropped the mapped main-yourLibraryX-* classes, so each lookup below tries the older selectors first and then falls back to the 1.3.4 structure. Selectors used:
- Row lookup:
#listrow-title-<uri>→.closest('.main-yourLibraryX-listItem, li, [role="treeitem"], [role="row"]') - Artwork slot:
.x-entityImage-imageContainer/.main-cardImage-imageWrapper/.main-yourLibraryX-listItemArtwork/.main-yourLibraryX-rowImage/[data-testid="entity-image"](first match wins). On 1.3.4+, where the row is an Encore ListRow: the firstsvg/imgin[class*="list-row__header-side"], climbing to its nearest ancestor that clips overflow (the rounded artwork box) - Rootlist enumeration:
Spicetify.Platform.RootlistAPI.getContents() - Rename:
Spicetify.Platform.RootlistAPI.renameFolder({uri}, newName) - Folders filter chip bar:
[role="listbox"][aria-label="Filter options"](react-aria listbox). Each native chip carriesdata-encore-id="chip"; the Folders chip is a clone of one, with the nativee-10451-legacy-chip--selectedclasses toggled for its active look - Folders filter list root (hidden while the Folders view is active):
.main-yourLibraryX-libraryRootlist/[data-testid="rootlist"]/.main-yourLibraryX-libraryItemContainer/.main-yourLibraryX-listItemContainer. On 1.3.4+: the library[role="grid"](ortreegrid) inside#Desktop_LeftSidebar_Id/.YourLibraryX, climbing to its wrapper directly under the scroll content ([data-overlayscrollbars-viewport] > div), so the search/sort row stays visible
If Spotify renames these classes in a future build, decoration will silently no-op (no errors thrown) and the issue will be a selector update.
Contributing
Section titled “Contributing”See CONTRIBUTING.md.
License
Section titled “License”MIT — see LICENSE.
Acknowledgments
Section titled “Acknowledgments”- SunsetTechuila/imaged-folders — prior art for folder images (now archived); selector patterns referenced here
- Dribbblish theme — first to introduce folder images, theme-locked
- bespoke-alpha/stdlib — auto-generated Spotify Platform type definitions, invaluable for reverse-engineering
renameFolder’s signature
Independent project. Not affiliated with or endorsed by Spotify or Spicetify.