> For the complete documentation index, see [llms.txt](https://docs.morpht.com/convivial-for-govcms/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.morpht.com/convivial-for-govcms/theme-settings/icons.md).

# Icons

Icons appear in item lists, on pages that set an **Icon**, and in some components. The site ships with the Phosphor library; Themers can add their own as SVG.

## Phosphor icons

Convivial for GovCMS includes the [Phosphor](https://phosphoricons.com) icon library. Editors can use icons in the **Icon** field on any page and in item lists.

1. Visit <https://phosphoricons.com> and search for an icon.
2. Select it; a panel appears at the bottom of the window.
3. Copy the icon name, e.g. `check-circle`.
4. Paste it into the **Icon** field.

## Custom icons

Custom icons are SVG files added as **Icon** media. Specifications:

* **Size:** 32 × 32px, with about 6px of margin on the sides or top depending on the design.
* **No strokes:** convert every stroke to an outline. Icons are coloured with the `fill` property.
* **Colour-aware:** replace every `fill="#xxxxxx"` with `fill="currentColor"` so the icon follows the palette, and remove any `style=""` attributes.
* **File name:** simple and lowercase, e.g. `about.svg`. The file name becomes the icon name.

A minimal example:

```xml
<svg width="32" height="32" viewBox="0 0 32 32" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
  <path d="M22.66 20.28C23.41 16.61 29.87 14.17 29.96 7.4 ... Z" fill="currentColor"/>
</svg>
```

To add one:

1. *Manage → Content → Media → Add media → Icon* (`/media/add/icon`) and upload the SVG, e.g. `morpht.svg`.
2. Ask a developer to clear the site caches — on GovCMS this is done from the GovCMS dashboard. A new icon is not available until then.
3. In any **Icon** field enter `custom.morpht` — the file name without `.svg`, not the media name. If a file with that name already exists the new one is renamed, e.g. `star_0`, so check the file name after upload.
4. View the page: the icon should render at the same size as the icons around it.

Uploaded icons live in the site's files, not its code, so an icon added on a test environment must be uploaded again on production. The SVG is placed in the page exactly as uploaded, which is why only Themers can add icons — upload only files you have made or checked yourself.

![Adding an icon](https://3733701002-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3fBWwpuJPUqPpT2ulMXp%2Fuploads%2Fgit-blob-7ae56c2637bb36833f99c43b2f4899d8fa50a9ec%2Fmedia-add-icon.png?alt=media)