Skip to content


Icons are specified by using a text string to describe an icon.

Try it out! Type in the box to see the icon it makes.

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), and the preceding keywords (if any) specifying modifiers (see Icon modifiers).

Here are some examples:

Specifier stringIcon generatedNotes
THere, T specifies the base icon as a text icon.
square THere, square is a modifier that encloses the base icon in a square.
square filled TCombining two modifiers; filled specifies that the square is a solid shape.
circle filled THere we use a non-Ascii character as the base icon. The circle modifier encloses the base icon in a circle.
search filled TThe search modifier encloses the base icon in a magnifying glass shape.
iconify:mdi:homeHere, the base icon is an Iconify icon.
square filled iconify:mdi:homeWe put the home icon in a filled square.
strike iconify:mdi:homeThe strike modifier draws a strike-through line over the base icon.
symbol:hand.raisedHere, the base icon as an SF Symbols icon.
flip-x symbol:hand.raisedThe flip-x modifier flips the base icon horizontally.

Base icon formats

File icons

File icons can only be used in packages. The icon is specified as a path to a .png or .svg image file in the package.

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

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.

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


Specifier stringIcon generated
ABC (or text:ABC)
monospaced ()

💡 Tip: Monospaced font

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

Iconify icons

Iconify 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 of available icons.

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

Some Iconify icons contain color information. These are automatically recognized by PopClip and will be rendered in color.


Specifier stringIcon generated

SF Symbols icons

Apple 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:<symbol name>.

Symbols are always drawn in the monochrome variant.


Specifier stringIcon generated

SVG Icons

The icon string can supply SVG source code for an icon. The format is svg:<svg string>.


svg:<svg xmlns="" width="1em" height="1em" viewBox="0 0 24 24"><path fill="currentColor" d="m6 10.95l-1.875 1.025l-2.975-5.2L7.75 3H10v1q0 .825.588 1.413T12 6q.825 0 1.413-.587T14 4V3h2.25l6.6 3.775l-2.95 5.15l-1.9-.95V21H6z"/></svg>


Data icons

The icon string can include raw image data as a data URL.

The format is: data:<mediatype>[;base64],<data>, where <mediatype> may be either image/svg+xml or image/png.

SVG Example

Specifier string:



PNG Example

Specifier string:



Icon modifiers

The following modifiers can be prefixed to the specifier string to alter how the icon is drawn.

Style modifiers

squareEnclose the icon in a square.
circleEnclose the icon in a circle.
searchEnclose the icon in a magnifying glass shape.
strikeDraw a strike-through line over the icon.
filledDraw the enclosing shape as a solid shape.
monospacedFor text icons only. Draw the text using a monospaced font.

Geometric transformations

flip-xFlip the icon horizontally.
flip-yFlip the icon vertically.
move-x=<percent>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=<percent>Move the icon vertically by the specified distance, expressed as percentage of the icon's height.
scale=<percent>Adjust the scale at which the icon is drawn. For example scale=120 to enlarge to 100%, or scale=90 to shrink to 90%.
rotate=<degrees>Rotate the icon by the specified number of degrees. For example rotate=90 to rotate 90 degrees anticlockwise.


Specifier stringIcon generated
flip-x symbol:signpost.right
move-y=-50 symbol:signpost.right
scale=50 symbol:signpost.right
rotate=90 symbol:signpost.right
square filled move-x=4 move-y=-4 scale=115 rotate=45 T

Color and aspect

preserve-colorThe 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-aspectIf 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.


  "icon": "preserve-color file:rainbow.png"

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

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 = () => {
  return [
      icon: popclip.input.text,