Custom SVG icons
A favorite can use your own SVG artwork instead of an SF Symbol. This page shows how to import a file, check the preview, set the size, and what each message on the import sheet means. Read it if you want a logo or a drawing in the sidebar, or if an import shows a warning or is refused.
On this page
What a custom icon is
A custom icon is your own vector artwork, such as a logo or an icon you drew, shown on a favorite’s sidebar row. Any ordinary SVG works. There is nothing to prepare: you do not need a template, guide boxes or a special file name. SidebarFavorites reads the shapes in the file, joins them into one outline and builds the sidebar symbol around it. Xcode is not required, because the app builds the symbol with the asset-catalog engine that ships with macOS.
Import an SVG
You import in the favorite editor, the window you open with + in the manager window or by editing an existing favorite. The file is copied into the app’s own Icons folder, so the original can move or change afterwards without affecting the favorite.
In the favorite editor, set Type to Custom SVG.
You seeAn Import SVG... button replaces the SF Symbol grid.
Click Import SVG... and choose an SVG file.
Before a file is chosen, Enlarged and the mock row below it show a placeholder. Import SVG... opens the file picker. You seeThe file name appears with a Replace... button, and the Preview section shows your artwork.
Check the Preview section.
The preview is what Finder will draw. If the app had to drop or flatten something, a warning row with an orange triangle appears below the preview. See Messages from the import sheet.
You seeTwo views of the same silhouette: an enlarged one, and a mock sidebar row at the real size, 16 pt tall.
Drag the Size slider if the icon looks too heavy or too light next to the other rows.
After import: the file name with Replace..., the Size slider from 50% to 150% with Reset, the Preview, and one warning below it. You seeThe percentage and both previews follow the slider as you drag.
Click Apply to see the icon in the real sidebar, or Add (Save for an existing favorite) to finish.
Apply is available only after you change something. With Add or Save the editor closes, and if Finder still shows a stale icon a Restart Finder banner appears in the manager window.
You seeWith Apply, the icon is saved, Finder restarts and the sidebar redraws while the editor stays open, so you can adjust the size against the real sidebar.
The size slider
The slider appears only for a custom icon. SF Symbols are drawn by macOS from Apple’s own outlines and have nothing to rescale. 100 percent draws your artwork at exactly the size of a system SF Symbol. That is the correct measurement but not always the right look: a wide or busy mark reads heavier than a narrow one at the same size, so you may want to move it down until it sits comfortably beside the other rows.
| Part | What it does | Choose it when |
|---|---|---|
| Size slider, 50% to 150% | Scales the artwork in the sidebar row. The value is shown beside the label. | The icon looks too large or too small next to the other sidebar icons. |
| 100% | Draws the artwork at the size of a system SF Symbol. | You have no reason to change it. It is the starting value. |
| Below 100% | Makes the icon smaller. | The icon is dense, wide or heavy. |
| Above 100% | Makes the icon larger. | The icon is thin or sparse and looks small. |
| Reset | Puts the slider back to 100%. It is disabled when the slider is already there. | You want to start the size over. |
Messages from the import sheet
The import sheet reports two kinds of message. A warning means the file was imported but something was dropped or will look different. A refusal means nothing could be imported.
Warnings
Each warning is a row with an orange triangle below the preview. The icon is still imported, and the preview shows exactly what survived.
| Message | What it means | What to do |
|---|---|---|
The embedded image was dropped - a sidebar icon can’t contain a photo or a PNG, only vector shapes. | The SVG contains a bitmap picture. Only vector shapes become part of the icon. | Replace the picture with vector artwork, or trace it in your drawing app, and import again. |
Live text isn’t converted to shapes. If lettering is missing from the preview, outline it in your drawing app and import again. | The file contains text that is still editable text, not shapes. | Convert the text to outlines in your drawing app, export the SVG again and import it. |
Some parts of this SVG can’t be reproduced in a symbol (<filter>). The preview shows what the icon will actually contain. | The SVG uses elements the app cannot turn into shapes. The message names them in angle brackets, so <filter> here stands for whichever elements your file has. | Look at the preview. If the icon is what you want, continue. If not, remove the effect or flatten it into plain shapes and import again. |
Colours and gradients flatten into one silhouette, so lighter areas won’t stay lighter. | The file uses a gradient or more than one colour. Finder draws one colour, so every filled area becomes the same tint. | If parts merge into a blob, simplify the artwork so the shape reads without colour. |
Much wider than it is tall. Sidebar icons are square, so this gets shrunk to fit its width - a compact mark works better than a wordmark. | The artwork is more than three times wider than it is tall, so it is scaled down to fit the width. | Use a compact mark instead of a wordmark, or crop the artwork closer. |
Much taller than it is wide. Sidebar icons are square, so this gets shrunk to fit its height - a compact mark reads better. | The artwork is more than three times taller than it is wide, so it is scaled down to fit the height. | Use a squarer mark, or crop the artwork closer. |
Almost nothing survives at 16 pt - the artwork is very thin, very small, or floating on a much bigger canvas. Thicker shapes or a tighter crop read better. | At sidebar size the artwork covers under 4 percent of its box, so it is nearly invisible. | Thicken the shapes, or set the artwork’s canvas close to its edges, then import again. |
This fills its box almost completely, so it will read as a solid block rather than as an icon. | The artwork covers more than about 72 percent of its box, so it looks like a filled square. | Add space inside the shape, or use a version with detail or an outline. |
Thin strokes and fine detail blur into grey at 16 pt. A bolder, simpler shape reads better. | Almost all of the artwork falls on partly lit pixels at 16 pt, so it looks smudged. | Use thicker strokes and fewer details, then import again. |
Refusals
A refusal opens an alert titled Can’t Use This SVG. The alert shows the message below, followed by a sentence that says what to try. Nothing is imported, and the favorite is unchanged.
| Message | Cause | Fix |
|---|---|---|
Couldn’t read this file. | The file is empty, was moved, or you do not have permission to open it. | Check that the file exists and that you can open it, then choose it again. |
This isn’t an SVG file. | The file is not an SVG. If it is XML with another root element, the alert says which one. | Export the artwork again as SVG from your drawing app. |
Couldn’t read this SVG. | The file is not well-formed XML. The alert adds a detail from the XML reader when there is one. | Export the SVG again from your drawing app. |
This SVG just wraps an image. | The SVG contains only an embedded photo or PNG and no vector shapes. | Export the artwork as paths, or trace the picture first. |
This SVG has no shapes we can use. | The file has none of the shapes the app can draw: paths, rectangles, circles and the like. | Draw or export the artwork as vector shapes. |
We couldn’t turn this SVG into a shape. | The shapes in the file come out empty. Live text and stroke-only artwork, such as a single line, are the usual cause. | Convert text and strokes to outlines in your drawing app and import again. |
If it does not work
| What you see | Cause | Fix |
|---|---|---|
| The alert Can’t Use This SVG. | The file was refused. | Find the message in the refusals table above. |
| A warning row with an orange triangle under the preview. | Part of the artwork was dropped or flattened. | Find the message in the warnings table above, then adjust the artwork or the size. |
| The sidebar shows a stale icon. | Finder has not redrawn the row yet. | Click Apply, or press Restart Finder on the banner in the manager window. |
| The icon looks too large, too small or too heavy. | 100 percent matches SF Symbols, which is not always the best look for your artwork. | Change the Size slider and click Apply. |
For more help, see Troubleshooting.