Skip to content

Enhanced Folders

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

Release License: MIT

Six playlist folders in the Your Library sidebar, each showing a custom cover image instead of the default folder icon

  • 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 MutationObserver so sidebar re-renders don’t thrash

Spotify treats playlist folders as client-side rootlist nodes; they have no first-class metadata API and no native edit dialog. This extension:

  1. Enumerates folders via Spicetify.Platform.RootlistAPI.getContents() (the modern Platform API — the legacy sp://core-playlist/v1/rootlist Cosmos endpoint no longer resolves in current Spotify)
  2. Registers an Edit folder details item in the folder context menu via Spicetify.ContextMenu
  3. Persists per-folder image (base64 JPEG, square-cropped to ~354px) and description in Spicetify.LocalStorage, keyed by folder ID
  4. 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 (forces position: relative on the slot at decoration time so the absolutely-positioned image stays bounded)
  5. 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

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.

  1. In Spotify, open Marketplace (the shopping-cart icon at the top left) and stay on the Extensions tab.
  2. 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.
  3. Hover the Enhanced Folders card, click its download button, then click Reload now.
  1. Download enhanced-folders.js (right-click → Save link as…) into your Spicetify Extensions folder:

    • Windows: %APPDATA%\spicetify\Extensions
    • macOS / Linux: ~/.config/spicetify/Extensions
  2. Enable it and apply:

    Terminal window
    spicetify config extensions enhanced-folders.js
    spicetify 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.

Edit folder details dialog with a custom cover image, the folder name and a description

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

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
}
}
}
  • 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.renameFolder signature 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.

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 first svg/img in [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 carries data-encore-id="chip"; the Folders chip is a clone of one, with the native e-10451-legacy-chip--selected classes 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"] (or treegrid) 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.

See CONTRIBUTING.md.

MIT — see LICENSE.

Independent project. Not affiliated with or endorsed by Spotify or Spicetify.