Skip to content


Icons may be specified in icon fields in several different ways:

Image files

If you specify the name of a PNG or SVG image file in the extension's package, it will be used.

Images should feature a monochrome shape on a transparent background. Variable opacity can be used for shading.

PNG icons should be at least 256 pixels high.

Text icons

Using a particular format, you can instruct PopClip to generate a text-based icon. Text icons can have a text: prefix, but it is optional.

Text icon examples

Specifier stringIcon generated
text:A or just A
circle 1
circle filled 本
square xyz
square filled !
square filled monospaced ()
search E
search filled monospaced £

Text icon format

The specifier format is <shape> <modifiers> <text>.

  • <shape> is optional and can be one of:
squareEncloses text in a round-cornered square.
circleEncloses text in a circle.
searchEncloses text in a magnifying glass shape.
  • <modifiers> are optional and can be any combination of:
filledSpecifies a solid filled shape instead of an outline shape.
monospacedSpecifies that the text be drawn with a monospaced font.
  • <text> can be up to three characters.

💡 Tip: Monospaced font

Punctuation symbols often look better in icons when drawn with the monospaced modifier.

Iconify icons

Iconify provides over 150,000 icons from a variety of open-source icon sets. Browse the catalog at

The format is iconify:<icon set prefix>:<icon name>.

Iconify icon examples

Specifier stringIcon generated

SF Symbols icons

Apple SF Symbols are available on macOS 11.0 and above. The icon catalog can be viewed by installing Apple's SF Symbols app on your Mac.

The format is symbol:<symbol name>.

SF Symbols icon examples

Specifier stringIcon generated

Raw data icons

You can supply the raw data for the icon in the icon field itself:

  • As SVG source: svg:<svg source>

  • As a data URL: data:<mediatype>[;base64],<data>, where <mediatype> may be either image/png or image/svg+xml.

Color handling

By default, PopClip treats icons as a mask images and renders them with a uniform fill color, ignoring any color information in the image. However, you can set the preserve color flag (see Icon options) to tell PopClip to keep the original color palette.

Special case: Emoji and Iconify icons

PopClip gives special treatment to emoji icons and color icons from Iconify. These icons are inherently colored, and PopClip will preserve their color even if preserve color is not set.

Icon properties

These optional properties can be placed in the config alongside the icon field to modify how PopClip draws it. Unlike action properties, icon properties set at the top level are not inherited by actions.

preserve colorBooleanIf true, the supplied icon will be displayed with its original color instead of being filled in white/black. Default is false.
preserve aspectBooleanIf true, the supplied icon will be displayed with its original aspect ratio instead of being scaled to fit a square. Default is false.
flip horizontalBooleanIf true, the supplied icon will be drawn horizontally flipped. Default is false.
flip verticalBooleanIf true, the supplied icon will be drawn vertically flipped. Default is false.
scaleNumberAdjust the scale at which the icon is drawn. For example 1.2 to enlarge, or 0.9 to shrink. The default is 1.0, no scaling.

Icon Preview tool

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.)

// #popclip
// name: Icon Preview
// entitlements: [dynamic]
// language: javascript
// module: true
exports.actions = (selection) => {
  return [{
    icon: selection.text,