# Custom icons

> Page: https://docs.plotwork.dev/custom-icons. Index of every page: https://docs.plotwork.dev/llms.txt

Upload your company's own service logos to an organisation, and the hosted service draws them in your diagrams as `icon=org:<name>`. Icon search, `map_icons` and automatic icon matching find them by name and by alias.

## TL;DR

| Question | Answer |
|---|---|
| What is a custom icon? | An SVG or PNG logo of at most 32 KB, saved on an organisation under a name such as `payments-api`. A diagram uses it as `icon=org:payments-api`. |
| Which plan? | Pro. The organisation's owner must be on Pro for icons to be uploaded and drawn. Pro keeps up to 100 icons per organisation. |
| Who can upload? | The organisation's owner or an admin, on the organisation's Icons tab in the portal. Members and readers see the icons. |
| Which calls draw them? | The hosted MCP server, the REST API and publishing, for the organisation's API keys and for members who chose the organisation for their own calls. |
| Does the local package draw them? | No. The local MCP server, the npm package, the command line and the GitHub Action know no `org:` name, and report one as an unknown icon. |
| Is an uploaded SVG safe? | It is read with a strict parser and written again from an allowlist of drawing elements. Scripts, event handlers, embedded HTML, style blocks and any link outside the file are refused with a reason. The picture is then drawn as an image, which cannot run code or load anything. |
| Can an agent upload an icon? | No. No tool takes an icon. The hosted service picks the icons from who is calling. |

## 1. Upload an icon

1. Open the organisation in the portal and choose the Icons tab.
2. Drop an SVG or PNG file on the upload area, or choose one.
3. Check the name. It is made from the file name, and you can change it: lowercase letters and digits joined by hyphens, at most 48 characters.
4. Add aliases, separated by commas, such as `payments service, Acme Pay`. Search and automatic matching find the icon by each of them.
5. Choose Upload icon.

Each icon is shown on a light and a dark background, the way diagrams draw it. Upload a file with a name that is already taken to replace that icon. To delete one, choose Remove on its tile.

| Role | Can do |
|---|---|
| Owner | See, upload, replace and delete icons |
| Admin | See, upload, replace and delete icons |
| Member | See the icons |
| Reader | See the icons |
| Organisation API key | See the icons, and draw with them |

If the owner moves from Pro to Free, the icons are kept but not drawn, and they are drawn again when the owner is back on Pro.

## 2. What a file may hold

The upload check keeps drawing and nothing else.

| Kept | Refused, with a reason | Left out quietly |
|---|---|---|
| Paths, circles, ellipses, rectangles, lines, polylines, polygons, groups | `script`, event handlers such as `onload` | Editor metadata, `desc`, Inkscape and Sodipodi data |
| Linear and radial gradients, clip paths, masks, inside the file | `foreignObject`, `iframe`, `image`, `use`, `a`, animations | `class` and `data-` attributes |
| Fill, stroke, opacity, transform, and the same properties in a `style` attribute | A `<style>` block: export with presentation attributes | Style properties that do not paint |
| A title | A DOCTYPE, entities, CDATA, a link or `url()` to anything outside the file | |
| | Text that is not converted to outlines, filters, patterns | |

| Limit | Value |
|---|---|
| File size | 32 KB |
| Elements | 2,000 |
| Nesting | 24 levels |
| Path commands | 4,000 |
| PNG size | 1,024 pixels on each side |
| Aliases | 10, each at most 60 characters |

A PNG keeps only the chunks that draw the picture, so text and EXIF metadata, which can hold a location, are not stored. Every id in an SVG is renamed after the icon, so two icons never share one.

When a file is refused, the Icons tab lists every reason beside the file, each with how to fix it. The REST API answers `422 icon.invalid` with the same list in `details`.

## 3. Use an icon in a diagram

Write the name after `org:`, the same way as any other icon:

```plotwork
flow "Checkout" direction=right
node shop  service  "Storefront"
node pay   service  "Acme Pay"   icon=org:acme-pay
node books database "Ledger"     icon=org:ledger
shop -> pay
pay -> books
```

An organisation icon is drawn in its own colors on a light tile, in both themes, like an official cloud icon. A node with no `icon=` whose whole label is an icon's name or alias, such as `"Acme Pay"`, draws that icon by itself, as it does for a bundled product name. With `icons=off` in the header it is not drawn, and the check suggests `icon=org:acme-pay` instead.

| Tool | What it does with your icons |
|---|---|
| `search_icons` | Lists `org:` icons first when they match as well as a bundled icon |
| `map_icons` | Resolves a name that is an icon's name or alias to that icon, with confidence `exact` |
| `draw_diagram`, `render_diagram`, `publish_diagram` | Draws `org:` icons |
| `validate_diagram` | Accepts `org:` names that exist, and suggests the nearest one for a misspelling |

## 4. Which calls use which icons

| Caller | Icons |
|---|---|
| An organisation's API key | That organisation's icons |
| A personal key, an agent connected by sign-in, the portal | The icons of the organisation chosen under "Organisation style for my own diagrams" on the Organisations page, or named by `brand.organization` in the repository settings, while you are a member |
| A diagram published into an organisation's library | That organisation's icons, whoever publishes |
| The local MCP server, the npm package, the CLI, the GitHub Action | None |

A picture that is already published keeps the icon it was drawn with, even after the icon is replaced or deleted. Publish it again to draw the new one.

## 5. Privacy

An icon is organisation configuration, like a brand: the file the check wrote, its name and aliases, the account that uploaded it, and when. It is deleted with the organisation. No diagram is stored to draw one. The operator's audit trail records that an icon was saved or deleted, with the organisation's id, and never its name or file. On Pro and Enterprise the organisation's own [audit log](https://docs.plotwork.dev/audit-log.md) records the icon's name and who saved or deleted it, never the file.

## See also

| Page | Why |
|---|---|
| [Brand themes](https://docs.plotwork.dev/brand-themes.md) | Paint the same diagrams in your company's colors |
| [Organisations](https://docs.plotwork.dev/organisations.md) | Roles, keys and the library icons sit beside |
| [Cloud icon names](https://docs.plotwork.dev/cloud-architecture/icon-names.md) | The bundled icons and how names are written |
| [Plans and billing](https://docs.plotwork.dev/plans-and-billing.md) | What Pro includes |
| [Privacy policy](https://docs.plotwork.dev/privacy-policy.md) | What is stored, and for how long |