Custom icons for shortcuts: what it does and where it breaks down

Three guides on making a shortcut icon on a Mac will give three different sets of steps, and all three are correct. The phrase does not name one feature. It covers a Finder alias, an item parked in the Dock, a Safari web app, and an entry in the Shortcuts app, and those four are built in different places, stored in different places, and removed in different ways. The reason an icon refuses to change, or opens the wrong thing when clicked, is almost never a mistyped step. It is that the thing on screen is not the thing the instructions were written for.

Four separate features share one description

The confusion is structural. Someone organising documents, someone who wants a website out of the browser, and someone automating a morning routine all reach for the same words, and the search results mix all three.

What gets created	What happens on click	Can you set your own image
Finder alias	The original file or folder opens	Yes, per alias
Item in the Dock	The original app or folder opens	Only by changing the original
Safari web app	The site opens in its own window	Yes, from the app's settings
Shortcuts app entry	A saved sequence of actions runs	Only from the supplied glyphs

Once any of these is sitting on the desktop or in the Dock, nothing about its appearance says which route produced it. The small arrow badge in the lower left marks an alias. Beyond that badge, a web app and an application look identical at a glance. Selecting the item and opening the info window, then reading the Kind field, is the fastest way back to solid ground.

Storage location differs too. A Safari web app lands in the Applications folder inside the home folder, not the system-wide one. Shortcuts entries live inside the Shortcuts app and never appear in the Finder at all. An alias sits wherever it was dropped. That matters at deletion time, because three of the four have different removal paths.

An alias is a pointer, and that is the whole story

A Finder alias records where the original lives. Select a file or folder, create the alias from the File menu, and the result carries the original name plus a suffix and that small arrow badge.

Because it is a pointer rather than a copy, the original can be moved to another folder or renamed and the alias still finds it. The failure mode follows from the same property: delete the original and the pointer survives with nothing to point at. A desktop icon that does nothing when clicked is usually this.

Custom images work per alias. Two aliases to one file can carry two different icons, which is useful when the same template is filed in several project folders and each needs to look distinct. The flip side is that setting a uniform look across a folder means repeating the operation once per item, since nothing propagates.

Dock items are mostly not the thing itself

Items placed in the Dock behave like aliases. Apple's documentation on the Dock states that dragging an item out and releasing it removes the alias only, and the item itself stays on the Mac. That sentence resolves a common panic: removing something from the Dock has not uninstalled it.

It also explains why a Dock icon cannot be restyled on its own. The Dock renders whatever the original looks like. To change the picture, change the app or folder it points at. People who try to select the Dock item and paste an image into it find no place to paste, because the Dock item is not a file.

One more detail is worth knowing before assigning muscle memory to positions. The Dock shows up to three recently used apps that are not already in it, separated from the rest by a divider line. Icons in that zone rotate as work changes. Anything clicked by position rather than by shape should live on the permanent side of the divider.

A Safari web app starts with the site's own icon

macOS has built this in since Sonoma 14. Open the page in Safari, choose File then Add to Dock from the menu bar, give it a name, and it is saved to the Applications folder inside the home folder, reachable from the Dock and from Spotlight.

What separates it from a tab is isolation. Apple states that a web app shares no browsing history, cookies, website data, or settings with Safari. Signing in inside the web app does not sign in inside Safari, and signing out of Safari does not sign out of the web app. That is a feature when the goal is to keep a work account and a personal account apart, and a surprise for anyone who expected the existing session to carry over.

The starting icon comes from what the site publishes. A site that only ships a small favicon produces a soft, low-resolution icon in the Dock. That is fixable after the fact, not before: open the web app, click its name in the menu bar, choose Settings, and the Application Name, Application URL, and Icon fields are all editable there. The URL field even offers a Set to Current Page button, so a web app created on the wrong page does not need rebuilding.

The Settings panel also carries Privacy and Extensions tabs. The Extensions tab governs Safari extensions. A Chrome Web Store extension used every day for ad filtering or password entry is a different thing and does not appear here.

Shortcuts app icons are picked from a fixed set

The Shortcuts app bundles actions into one runnable item. The word shortcut is doing entirely different work in that sentence, and search results mix it with the others constantly.

Its icons follow different rules. In the shortcut editor, clicking the icon beside the name opens a picker of supplied glyphs and colours, and new shortcuts get one of fifteen colours assigned automatically. There is no field for a photograph or a company logo. The picker is the whole range.

So if instructions mention glyphs or a palette of fifteen colours, they describe this feature. Anyone trying to put a website in the Dock will read those steps, fail to find the screen being described, and conclude something is broken on their machine.

Chrome adds a fifth variant with its own rules

Safari is not the only browser that can turn a page into something app-shaped. Chrome offers Install page as app, reached from the More menu under Cast, save, and share, and on some sites directly from an install button at the right of the address bar. The result gets its own window and its own icon, and the full list is managed at the internal apps page.

The behaviour that has no equivalent in the other four routes is that the site retains a say in how the app is labelled. Chrome's documentation explains that when a web app wants to update its name or icon, Chrome notifies the user, who can accept the update, ignore it, or uninstall the app. The same page adds a warning: if the change looks malicious, such as an icon suddenly resembling a different app, uninstall it.

For anyone who deliberately set a custom image, that notification is the moment to choose ignore. Accepting it replaces the chosen icon with whatever the site now ships. Nothing changes silently, but nothing is permanently locked either.

Removal has two levels here. Opening the app and choosing Uninstall from the More menu removes the app. Ticking the option to also delete data from Chrome clears the site data as well, which means the next visit starts from a signed-out state. Leaving that box unticked keeps the session alive, which is the right choice when the app is being rebuilt rather than abandoned.

This route is worth knowing about for a second reason. Chrome extensions keep working inside these windows, which is the piece the Safari route cannot offer. Anyone whose daily work depends on an ad filter or a password manager from the Chrome Web Store will find that a Safari web app quietly drops all of them.

Where each route actually breaks

Symptoms map cleanly back to causes once the four routes are separated:

• Paste is greyed out in the info window. Either the large preview image is selected instead of the small icon at the top, or the target is one of the built-in folders. Apple lists Applications, Library, System, and Users as folders that cannot be customised, while the home folder can be.
• The image pastes but looks soft. The source image is too small. The Dock and the app switcher render at different sizes, and a favicon-sized file survives neither.
• The icon reverts after an update. An icon set on an application bundle can be replaced when that application updates.
• Clicking opens something unexpected. The item is not the kind of thing it was assumed to be.

The last one is the most common and the hardest to spot, because everything looks the same on the desktop. Checking the Kind field in the info window takes a few seconds and ends the guessing.

Reverting a custom icon uses a verb people do not look for. Select the small icon at the top of the info window and choose Cut from the Edit menu. Not Delete. Cut.

Decide the route before the icon

Three questions settle which of the four is being built. Is the target a website or a local file? Does it need a session separate from the browser, and separate from other copies of itself? Does the image need to be chosen rather than inherited?

The second question is the one that cannot be answered later. A site opened in ordinary browser windows shares one cookie store, so signing into a second account pushes the first one out, and no amount of icon work changes that. Routes that assign each app its own profile avoid it entirely. What can be separated, and how far, is listed under Features, and the creation flow is written out step by step in the Guide.

If the site in question is a mainstream one, check whether it is already covered as a preset before hunting for a URL and an icon file: the current line-up is at Supported services. Then read Pricing before building the fifth or sixth app, because that is where free tiers usually stop.

What to change first

Open the info window on whichever icon is currently misbehaving and read its Kind field. That single check tells you whether the instructions you have been following apply at all. If the target is a website and the session needs to stay separate from the browser, build it as a standalone app rather than an alias, using the built-in Safari route or a dedicated tool such as Kagemusha.