# Icons Icons are specified by using a text string to describe an icon. _(An interactive icon preview tool is available in the online version of this page, at . Alternatively, a PNG rendering of any icon specifier can be fetched from `https://icons.popclip.app/icon?specifier=` — the preview links in the tables below use this.)_ **Tip: Icon Picker in the app** PopClip has a built-in icon browser: choose **Icon Picker** from the Tools menu in PopClip's settings window (or press ⌥⌘I). Search the Iconify icon libraries, preview any icon specifier with modifiers live, and copy the resulting string for use in your config. An icon specifier string describes an icon using a simple text-based format. The string consists of a series of space-separated keywords, with the final keyword specifying the **base icon** (see [Base icon formats](#base-icon-formats)), and the preceding keywords (if any) specifying **modifiers** (see [Icon modifiers](#icon-modifiers)). Here are some examples: | Specifier string | Icon generated | Notes | | -------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | `T` | [preview](https://icons.popclip.app/icon?specifier=T) | Here, `T` specifies the base icon as a [text icon](#text-icons). | | `square T` | [preview](https://icons.popclip.app/icon?specifier=square%20T) | Here, `square` is a modifier that encloses the base icon in a square. | | `square filled T` | [preview](https://icons.popclip.app/icon?specifier=square%20filled%20T) | Combining two modifiers; `filled` specifies that the square is a solid shape. | | `circle filled T` | [preview](https://icons.popclip.app/icon?specifier=circle%20filled%20T) | The `circle` modifier encloses the base icon in a circle. | | `search filled T` | [preview](https://icons.popclip.app/icon?specifier=search%20filled%20T) | The `search` modifier encloses the base icon in a magnifying glass shape. | | `iconify:mdi:home` | [preview](https://icons.popclip.app/icon?specifier=iconify%3Amdi%3Ahome) | Here, the base icon is an [Iconify icon](#iconify-icons). | | `square filled iconify:mdi:home` | [preview](https://icons.popclip.app/icon?specifier=square%20filled%20iconify%3Amdi%3Ahome) | We put the home icon in a filled square. | | `strike iconify:mdi:home` | [preview](https://icons.popclip.app/icon?specifier=strike%20iconify%3Amdi%3Ahome) | The `strike` modifier draws a strike-through line over the base icon. | | `symbol:hand.raised` | [preview](https://icons.popclip.app/icon?specifier=symbol%3Ahand.raised) | Here, the base icon as an [SF Symbols icon](#sf-symbols-icons). | | `flip-x symbol:hand.raised` | [preview](https://icons.popclip.app/icon?specifier=flip_x%20symbol%3Ahand.raised) | The `flip-x` modifier flips the base icon horizontally. | ## Base icon formats ### File icons File icons can only be used in [packages](https://www.popclip.app/dev/packages.md). The icon is specified as a path to a `.png` or `.svg` image file in the package. ```json { "icon": "icon.png" } ``` A good icon will feature a monochrome shape on a transparent background. Variable opacity can be used for shading. PNG icons should be at least 256 pixels high. **Note: File icons with modifiers** File icons can be used with modifiers by adding the prefix `file:`, for example: ``` { "icon": "strike file:icon.png" } ``` ### Text icons Text icons can include up to 3 characters and are specified as the text itself. The prefix `text:` can optionally be used. ```json { "icon": "T" } ``` Text icons are drawn using the system font. Adding the `monospaced` modifier will draw the icon in a monospaced variant. If the text icon is a single emoji without modifiers, it rendered in color. Examples: | Specifier string | Icon generated | | --------------------- | ------------------------------------------------------------------------------------- | | `ABC` (or `text:ABC`) | [preview](https://icons.popclip.app/icon?specifier=ABC) | | `@` | [preview](https://icons.popclip.app/icon?specifier=%40) | | `本` | [preview](https://icons.popclip.app/icon?specifier=%E6%9C%AC) | | `()` | [preview](https://icons.popclip.app/icon?specifier=%28%29) | | `monospaced ()` | [preview](https://icons.popclip.app/icon?specifier=monospaced%20%28%29) | | `😵‍💫` | [preview](https://icons.popclip.app/icon?specifier=%F0%9F%98%B5%E2%80%8D%F0%9F%92%AB) | **Note: 💡 Tip: Monospaced font** Punctuation symbols often look better in icons when drawn with the `monospaced` modifier. ### Iconify icons [Iconify](https://iconify.design/) provides access to over 200,000 icons from a variety of open-source icon sets, using a unified naming system. The Iconify website provides a [catalog](https://icon-sets.iconify.design/) of available icons. The format is `iconify::`. Some Iconify icons contain color information. These are automatically recognized by PopClip and will be rendered in color. Examples: | Specifier string | Icon generated | | ---------------------------- | ---------------------------------------------------------------------------------- | | `iconify:ion:fish` | [preview](https://icons.popclip.app/icon?specifier=iconify%3Aion%3Afish) | | `iconify:solar:flag-bold` | [preview](https://icons.popclip.app/icon?specifier=iconify%3Asolar%3Aflag-bold) | | `iconify:logos:spotify-icon` | [preview](https://icons.popclip.app/icon?specifier=iconify%3Alogos%3Aspotify-icon) | ### SF Symbols icons Apple [SF Symbols](https://developer.apple.com/sf-symbols/) are available on macOS 11.0 and above. (Symbol availability may vary by macOS version). The icon catalog can be viewed by installing Apple's SF Symbols app on your Mac. The format is `symbol:`. Symbols are always drawn in the monochrome variant. Examples: | Specifier string | Icon generated | | ----------------------- | --------------------------------------------------------------------------- | | `symbol:flame` | [preview](https://icons.popclip.app/icon?specifier=symbol%3Aflame) | | `symbol:hand.raised` | [preview](https://icons.popclip.app/icon?specifier=symbol%3Ahand.raised) | | `symbol:signpost.right` | [preview](https://icons.popclip.app/icon?specifier=symbol%3Asignpost.right) | ### SVG Icons The icon string can supply SVG source code for an icon. The format is `svg:`. **Example** `svg:` generates: [preview](https://icons.popclip.app/icon?specifier=svg%3A%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20width%3D'1em'%20height%3D'1em'%20viewBox%3D'0%200%2024%2024'%3E%3Cpath%20fill%3D'currentColor'%20d%3D'm6%2010.95l-1.875%201.025l-2.975-5.2L7.75%203H10v1q0%20.825.588%201.413T12%206q.825%200%201.413-.587T14%204V3h2.25l6.6%203.775l-2.95%205.15l-1.9-.95V21H6z'%2F%3E%3C%2Fsvg%3E) ### Data icons The icon string can include raw image data as a [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs). The format is: `data:[;base64],`, where `` may be either `image/svg+xml` or `image/png`. **SVG Example** Specifier string: `data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2224%22%20height%3D%2224%22%20viewBox%3D%220%200%2024%2024%22%3E%3Cpath%20fill%3D%22currentColor%22%20d%3D%22M5.5%2015v-4.5H4V9h3v6H5.5ZM9%2015v-2.5q0-.425.288-.713T10%2011.5h2v-1H9V9h3.5q.425%200%20.713.288T13.5%2010v1.5q0%20.425-.288.713t-.712.287h-2v1h3V15H9Zm6%200v-1.5h3v-1h-2v-1h2v-1h-3V9h3.5q.425%200%20.713.288T19.5%2010v4q0%20.425-.288.713T18.5%2015H15Z%22%2F%3E%3C%2Fsvg%3E` generates: [preview](https://icons.popclip.app/icon?specifier=data%3Aimage%2Fsvg%2Bxml%2C%253Csvg%2520xmlns%253D%2522http%253A%252F%252Fwww.w3.org%252F2000%252Fsvg%2522%2520width%253D%252224%2522%2520height%253D%252224%2522%2520viewBox%253D%25220%25200%252024%252024%2522%253E%253Cpath%2520fill%253D%2522currentColor%2522%2520d%253D%2522M5.5%252015v-4.5H4V9h3v6H5.5ZM9%252015v-2.5q0-.425.288-.713T10%252011.5h2v-1H9V9h3.5q.425%25200%2520.713.288T13.5%252010v1.5q0%2520.425-.288.713t-.712.287h-2v1h3V15H9Zm6%25200v-1.5h3v-1h-2v-1h2v-1h-3V9h3.5q.425%25200%2520.713.288T19.5%252010v4q0%2520.425-.288.713T18.5%252015H15Z%2522%252F%253E%253C%252Fsvg%253E) **PNG Example** Specifier string: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEABAMAAACuXLVVAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAJcEhZcwAAFiUAABYlAUlSJPAAAAAwUExURUdwTAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACVM9DkAAAAPdFJOUwDcIDTLUFYGEqLpZfaDQdxVBh4AAAIbSURBVHja7doxS0JRGMZxuVI6BUG4GBhtDoHQkmPQViSBtAsVjS66CNIuLrWF0CcIaalojsAhXEMaGoJwvOCiCbfR9w5dXI6P4v/3Be4D5/C87xFjMQAAAAAAAAAAAAAAAAAAAADAIknsTmvPTYD4/vqUUmUnASrBtH6vCEAAAhCAAARY9gBv6nF87WYhqR9E2DTfH/y4CeCdRrg1AdJurkD0utaafH/8IVhYd9qTAMOt2X8/+WBO4Lg8+wCVwuT7/rPgBPrdSYB3wRX0eu5LIFIz474EIt9sZ+ISWLsTl0C2Ky6BnrgEquoS+A60JWDnkKYE2uISsHMoJTiBekFcAnlxCXjqEmiYOeRfCq5gcdlLwC6jr4ISCC2jKcEVrMxTCQwUJWCv4KHgBOwyOhKcQGgZ7eQEy2jB1rB4GR08iZfRe0EN12wJ3IiX0cGXeA4pSsDOIUUJhOZQR1DDdXUJ5MUl4KlLwC6jY8EullBfwZWC+Dlgr6C/jFewJr6CsWKg/U0gNIfSijnUFc+hF3EJrKpLoK8ugZa4BOzvcpISKIlLwDsSl0BTXAKJkrgE4uoSyIpLIPkpLoGquAQS9kWq+GHQYxOYoxfpWPIcCMSbgLoEGuoSOBGXQGgODR8v/nXu6HTsHArGEX/t3si5L4FIIzcBKhlxgGYgDpAlAAEIQAACEGBxAviOFpLtqQleDAAAAAAAAAAAAMCi+gOiz1VAs+KXUwAAAABJRU5ErkJggg==` generates: [preview](https://icons.popclip.app/icon?specifier=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAAQAAAAEABAMAAACuXLVVAAAABGdBTUEAALGPC%2FxhBQAAAAFzUkdCAK7OHOkAAAAJcEhZcwAAFiUAABYlAUlSJPAAAAAwUExURUdwTAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACVM9DkAAAAPdFJOUwDcIDTLUFYGEqLpZfaDQdxVBh4AAAIbSURBVHja7doxS0JRGMZxuVI6BUG4GBhtDoHQkmPQViSBtAsVjS66CNIuLrWF0CcIaalojsAhXEMaGoJwvOCiCbfR9w5dXI6P4v%2F3Be4D5%2FC87xFjMQAAAAAAAAAAAAAAAAAAAADAIknsTmvPTYD4%2FvqUUmUnASrBtH6vCEAAAhCAAARY9gBv6nF87WYhqR9E2DTfH%2Fy4CeCdRrg1AdJurkD0utaafH%2F8IVhYd9qTAMOt2X8%2F%2BWBO4Lg8%2BwCVwuT7%2FrPgBPrdSYB3wRX0eu5LIFIz474EIt9sZ%2BISWLsTl0C2Ky6BnrgEquoS%2BA60JWDnkKYE2uISsHMoJTiBekFcAnlxCXjqEmiYOeRfCq5gcdlLwC6jr4ISCC2jKcEVrMxTCQwUJWCv4KHgBOwyOhKcQGgZ7eQEy2jB1rB4GR08iZfRe0EN12wJ3IiX0cGXeA4pSsDOIUUJhOZQR1DDdXUJ5MUl4KlLwC6jY8EullBfwZWC%2BDlgr6C%2FjFewJr6CsWKg%2FU0gNIfSijnUFc%2BhF3EJrKpLoK8ugZa4BOzvcpISKIlLwDsSl0BTXAKJkrgE4uoSyIpLIPkpLoGquAQS9kWq%2BGHQYxOYoxfpWPIcCMSbgLoEGuoSOBGXQGgODR8v%2FnXu6HTsHArGEX%2Ft3si5L4FIIzcBKhlxgGYgDpAlAAEIQAACEGBxAviOFpLtqQleDAAAAAAAAAAAAMCi%2BgOiz1VAs%2BKXUwAAAABJRU5ErkJggg%3D%3D) ## Icon modifiers The following modifiers can be prefixed to the specifier string to alter how the icon is drawn. ### Style modifiers | Keyword | Description | | ------------ | ----------------------------------------------------------- | | `square` | Enclose the icon in a square. | | `circle` | Enclose the icon in a circle. | | `search` | Enclose the icon in a magnifying glass shape. | | `strike` | Draw a strike-through line over the icon. | | `filled` | Draw the enclosing shape as a solid shape. | | `monospaced` | For text icons only. Draw the text using a monospaced font. | ### Geometric transformations | Keyword | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `flip-x` | Flip the icon horizontally. | | `flip-y` | Flip the icon vertically. | | `move-x=` | Move the icon horizontally by the specified distance, expressed as percentage of the icon's width. For example `move-x=10` to move 10% right or `move-x=-5` to move 5% left. | | `move-y=` | Move the icon vertically by the specified distance, expressed as percentage of the icon's height. | | `scale=` | Adjust the scale at which the icon is drawn. For example `scale=120` to enlarge to 120%, or `scale=90` to shrink to 90%. | | `rotate=` | Rotate the icon by the specified number of degrees. For example `rotate=90` to rotate 90 degrees anticlockwise. | Examples: | Specifier string | Icon generated | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `symbol:signpost.right` | [preview](https://icons.popclip.app/icon?specifier=symbol%3Asignpost.right) | | `flip-x symbol:signpost.right` | [preview](https://icons.popclip.app/icon?specifier=flip_x%20symbol%3Asignpost.right) | | `move-y=-50 symbol:signpost.right` | [preview](https://icons.popclip.app/icon?specifier=move_y%3D-50%20symbol%3Asignpost.right) | | `scale=50 symbol:signpost.right` | [preview](https://icons.popclip.app/icon?specifier=scale%3D50%20symbol%3Asignpost.right) | | `rotate=90 symbol:signpost.right` | [preview](https://icons.popclip.app/icon?specifier=rotate%3D90%20symbol%3Asignpost.right) | | `square filled move-x=4 move-y=-4 scale=115 rotate=45 T` | [preview](https://icons.popclip.app/icon?specifier=square%20filled%20move_x%3D4%20move_y%3D-4%20scale%3D115%20rotate%3D45%20T) | ### Color and aspect | Keyword | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `preserve-color` | The base icon will be displayed in its original colors instead of used as a monochrome mask. (This is applied implicitly to emoji and color Iconify icons.) | | `preserve-aspect` | If the base icon is not square, it by default rendered into a square canvas. With this modifier, the icon will be rendered with its original aspect ratio. | Example: ```json { "icon": "preserve-color file:rainbow.png" } ``` **Tip: Negative modifiers** In some cases it may be useful to explicitly negate a modifier. This is done by appending `=0`. For example, to remove the implicit color rendering from an Iconify icon, use `preserve-color=0`. ## Icon Preview tool ![](https://www.popclip.app/dev/media/anim-icon-preview-2.mp4 "The Icon Preview extension.") As a handy tool, the following snippet defines an extension that will display the icon for any text string you select. (To see how to install this, see [Snippets](https://www.popclip.app/dev/snippets.md).) ```javascript // #popclip // name: Icon Preview // entitlements: [dynamic] defineExtension({ actions: () => { return [ { icon: popclip.input.text, }, ]; }, }); ```