Appearance

The browser tab, the icon, what a link looks like when somebody pastes it, and adding it to a phone's home screen.

Settings › Appearance. The details everybody notices only when they are wrong, and nobody remembers to ask for.

Settings, Appearance section: the name and description, the icon, and a preview of what a link to the application looks like when pasted.Settings, Appearance section: the name and description, the icon, and a preview of what a link to the application looks like when pasted.
The link preview is shown as it will appear, rather than described.

What is here#

Name and descriptionThe browser tab, and what a search engine shows
IconThe favicon, and the icon if it is installed to a phone
Link previewThe title, description and picture when somebody pastes the address into a message
Home screenWhether it can be installed to a phone, and how it behaves when it is

Why these are settings and not requests#

Three reasons, and they are the same three that put redirects and search-engine rules here too:

  • Nobody asks for them. A tab that says localhost, a link that unfurls in Slack as a bare URL with no picture, a home-screen icon that is a blank page — these are noticed when wrong and never specified when right.
  • The next build would overwrite them. Written into the source, a page title is a thing somebody has to undo.
  • They take effect without a build. Change one and it applies on the next deployment, and on the preview when you Restart the preview — and the icon does not even wait for either. No build spent, nothing to review.

The builder is told which of these are handled here, so it does not write a competing page title into the code. Two of those take turns winning, which looks like a bug nobody can reproduce.

The icon#

Drop an image onto the Icon box, or press choose a file. That is the whole of it — it is uploaded, converted, and set as the icon in one step.

Any image works. A PNG, a JPEG, a WebP or a GIF, at whatever size somebody in marketing sent it. It is converted to the sizes a browser actually draws — 16, 32 and 48 pixels — so you never have to produce those yourself.

A square one is ideal, and anything else is padded rather than cropped. A wordmark that arrives 600×200 keeps its whole name with transparent space above and below it. Cropping it square would keep the middle third and lose the word, which is worse than a small logo.

If the picture is already in your published files, there is a picker under the box to choose it instead of uploading it twice. Either way it ends up published, so the application can use the same image on a page at the same address as everything else it serves.

The icon appears without deploying#

Everything else on this screen travels to the application inside its container and applies the next time you deploy. The icon does not: it is served by the platform in front of the application, at the address /favicon.ico on each of its domains, so it shows up on what is already running as soon as you set it.

That address matters more than it sounds. A browser asks for /favicon.ico at the root of a site whatever it is looking at — a PDF opened from /_files/, an address you have bookmarked, an entry in the history — because none of those have a page to read a setting from. Serving it there is what makes the icon appear everywhere rather than only on pages.

The same box, under When somebody shares a link. Drop an image in or choose a file.

Wide rather than square here — around 1200×630 is what Slack, WhatsApp, LinkedIn and the rest crop to. This one does travel with the container, so it applies the next time you deploy.

Both pictures reach the application as /_files/… paths rather than absolute URLs, so the same value is right on the platform address, on your own domain, and in both environments.