How it works
How SidebarFavorites puts its own icon on a Finder sidebar row, part by part: the code on the row, the helper bundle, Both icons mode, Finder restarts and the SVG pipeline. Read it if you are curious or want to contribute. You do not need it to use the app.
On this page
The mechanism in brief
A row in Finder’s sidebar can carry a hidden four-character code. The code points at an icon. A small helper bundle, kept in the app’s data folder, declares which icon belongs to which code. Finder looks the code up and draws that icon on the row.
SidebarFavorites hands out one code for each favorite, writes it on the row, and keeps the helper bundle up to date. Nothing has to keep running for the icons to stay: no background process, no login item, no extension.
| Part | What it is | Where it lives |
|---|---|---|
| Row property | A four-character code on a sidebar row. | Finder’s Favorites list. |
| Helper bundle | A small app bundle that declares an icon for each code. | The app’s data folder. |
| Both icons helper | An extra helper for each favorite in Both icons mode. | The AdvancedApps folder. |
| SVG pipeline | The steps that turn an imported SVG into a symbol. | Inside the SidebarFavorites app. |
The row property
Every row in Finder’s Favorites list can carry a private property that holds a four-character code. Finder asks Launch Services, the macOS service that knows which types and icons are registered, for the icon that belongs to the code. SidebarFavorites allocates one code for each favorite and sets it on the row. The code is stored in config.json as osType and never changes.
Property key
com.apple.LSSharedFileList.OverrideIcon.OSType| Fact | Value |
|---|---|
| Shape | The letter S followed by three characters, such as S000, S001, S002. |
| Case | Case-sensitive. S00A and S00a are different codes. |
| Allocation | The lowest free code is used, and the app checks that no other app already declares it. |
The helper bundle
Launch Services needs a registered bundle that declares which icon goes with which code. SidebarFavorites keeps exactly one such bundle for all favorites. It declares one type for each favorite, tags it with the favorite’s code and names the SF Symbol to draw. Imported SVGs are compiled into a symbol catalog inside the same bundle.
Helper bundle
~/Library/Application Support/SidebarFavorites/SidebarFavoritesIcons.app| Question | Answer |
|---|---|
| Does it contain code? | No program code. Its executable is a 17-byte shell script that does nothing. |
| Why is there an executable at all? | macOS registers a bundle cleanly only when its executable points at something that can run. |
| Is it ever launched? | No. It is registered with Launch Services and never opened. |
| When is it rebuilt? | When a favorite is added, changed or removed. When nothing changed, the app skips the rebuild. |
The Settings window links to the bundle in its Helper App row, so you can reveal it in Finder yourself.
Both icons mode
A folder that has an icon of its own can make Finder draw that icon over the sidebar code. Both icons mode keeps your sidebar glyph visible as well. It adds one extra helper for each favorite you switch it on for. Finder draws a sidebar row differently when a Finder Sync extension claims the folder, and that route ignores the folder’s own icon. For how to choose the mode, see Keeping both icons.
| Question | Answer |
|---|---|
| What the app generates | One small host app with a Finder Sync extension inside it, carrying that favorite’s artwork. |
| Where it lives | In the AdvancedApps folder next to the helper bundle. |
| What stays running | Only the extension, at about 6 MB. The host app quits a few seconds after it registers the extension. |
| What it is called in System Settings | SBF- followed by the favorite’s name. |
| What stays underneath | The normal icon code stays on the row. If you disable the extension, the row falls back to that icon. |
Both icons helpers
~/Library/Application Support/SidebarFavorites/AdvancedApps/Finder restarts
Finder caches sidebar icons, so a change to a row that is already on screen can stay invisible until Finder relaunches. SidebarFavorites never restarts Finder by itself. Quitting Finder aborts a copy in progress and closes every open window, tab and rename, so the app only offers the restart and waits for you.
| Situation | Restart needed? | Why |
|---|---|---|
| You add a favorite and the app adds its row. | No. | A row inserted with its code already set draws correctly straight away. |
| You add a favorite for a folder that is already in your sidebar. | Yes. | The row was already on screen, and its icon property changed. |
| You change the symbol, the SVG or the size of an existing favorite. | Yes. | The code stays the same, but the artwork behind it changed, and Finder keeps drawing the cached artwork. |
| You use Remove All Sidebar Icons and a row you added yourself had its icon cleared. | Yes. | Finder keeps drawing the cleared icon until it relaunches. |
| You open the app and nothing changed. | No. | No row icon changed, so the app skips the helper rebuild. |
When a restart is owed, the main window shows the banner Some icon changes need Finder to restart before they appear.
Only these three actions restart Finder:
| Action | Where you find it |
|---|---|
| The Restart Finder button. | On the banner in the main window. |
| The Restart Finder button. | In the Actions section of the Settings window. |
| The Apply button. | In the favorite editor. Save and Add do not restart Finder. |
From SVG to symbol
Finder draws sidebar icons from symbols, not from SVG files. When you import an SVG, the app turns it into a symbol in four stages, always in this order. The stages run on the copy stored in Icons/ whenever the helper bundle is rebuilt, and your original file is never changed.
| Stage | What happens | Source file |
|---|---|---|
| 1. Parse | Shapes, groups, transforms, styles and strokes are flattened into one filled outline. | SVGGeometryParser. |
| 2. Validate | The import is refused only when the file cannot be read, is not an SVG, is malformed or has no drawable shapes. Everything else becomes a warning. See SVG warnings. | SymbolValidator. |
| 3. Template | The outline is fitted to the height of a symbol, scaled by your size slider, and wrapped in the SF Symbols template that the compiler expects. | SymbolTemplateSynthesizer. |
| 4. Compile | All custom symbols become one Assets.car inside the helper bundle, built by the asset-catalog engine that ships with macOS. One icon that fails to compile does not stop the others. | SymbolCatalogBuilder. |
Where things live
Everything the app stores is under one folder in your Library. Your favorites and settings are in config.json, your imported SVGs are in Icons/, and the helper bundle sits beside them. The full list of files is on config.json. To open the data folder, choose Finder then Go then Go to Folder….
Data folder
~/Library/Application Support/SidebarFavorites/Contributors can read the full write-up in docs/ARCHITECTURE.md on GitHub.