# Icons

At a bare minimum you'll want to include PDF images for light mode icons so they can be used for all views where your Component appears within the RapidWeaver Elements UI.

{% hint style="info" %}
**Important:** The PDF graphic for your icon should have a transparent background so it can be composited in app on to the background tile to give a consistent look.
{% endhint %}

### Standard Icon

All Elements require an icon.pdf file for light mode. If the dark-mode.pdf file isn't provided, icon.pdf will be used in Dark Mode.

* **icon.pdf (Required), 1:1 ratio, e.g. 128x128 (Square)**
* icon-dark.pdf (optional), 1:1 ratio, e.g. 128x128 (Square)

### Palette Icons

The Palette image should be named paletteIcon.pdf and paletteIcon-dark.pdf for Dark Mode. If the paletteIcon-dark.pdf file isn't provided, paletteIcon.pdf will be used in Dark Mode.

* **paletteIcon.pdf (Required), 1:2 ratio, e.g. 128x256 (landscape)**
* paletteIcon-dark.pdf (optional), 1:2 ratio, e.g. 128x256 (landscape)

### Asset Placement

All Icon files should be placed at the root of the Component alongside the info.json file.

<figure><img src="https://github.com/realmacsoftware/rapidweaver-elements-docs-api/blob/main/.gitbook/assets/CleanShot%202024-10-18%20at%205 .29.48@2x.png" alt=""><figcaption><p>Finder window showing the icon files inside of a typical Element.</p></figcaption></figure>

### How to add a Custom Icon to your Component

Watch the short video below to learn more about adding custom icons to your Components.

{% embed url="<https://www.youtube.com/watch?v=qZOiHiWnjW8>" %}

### Sketch Example File

Your pdf icons **MUST be on a transparent background**.\
The background should not be exported as this is generated in Elements.

<figure><img src="https://github.com/realmacsoftware/rapidweaver-elements-docs-api/blob/main/.gitbook/assets/CleanShot%202024-12-02%20at%2011 .02.57@2x.png" alt=""><figcaption></figcaption></figure>

<figure><img src="https://github.com/realmacsoftware/rapidweaver-elements-docs-api/blob/main/.gitbook/assets/CleanShot%202024-08-21%20at%2011 .39.38@2x.png" alt=""><figcaption><p>Showing background in Sketch (for design purposes only)</p></figcaption></figure>

We've provided an example Sketch document below you can use to get started.

***

### Experimental / Unsupported - Banner Icons

{% hint style="info" %}
⚠️ While this feature works, please do not use it as **it may be removed in a future build**.
{% endhint %}

There is some unfinished experimental support for banner style icons, these are great for layout style components. However, this style of icon may not be supported when Elements ships, please use with caution and ensure you also include the standard style of icon.

* bannerLayer1.png
* bannerLayer1-Dark.png (optional)

Banner icons can be layered, and each layer can represent a different colour in the Theme Studio. For example this icon uses four layers and three of those layers will be tinted with the Theme colour.

* bannerLayer1.png
* bannerLayer2-brand-500.png
* bannerLayer3-brand-200.png
* bannerLayer4-surface-500.png

Banner images should be 512px in width, but can be as short or tall as you need. Banner icons will appear the same in both grid and list.

<figure><img src="https://github.com/realmacsoftware/rapidweaver-elements-docs-api/blob/main/.gitbook/assets/CleanShot%202024-05-12%20at%206 .51.51@2x%20(1).png" alt=""><figcaption><p>Element Library: Banner icons (Pre-Beta Build 22484)</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.realmacsoftware.com/elements-docs/elements-language/component/icons.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.