The config dictionary
PopClip is very flexible about how you name keys. In this documentation you'll mostly see keys named in lowercase with spaces, for example
key name. However, PopClip will treat
KEY_NAME as equivalents.
I tend to use
key name in YAML, and
keyName in JSON, but you can use whatever you prefer.
Before diving in to the details, let's look at an example config dictionary for a published extension. This is based on the Yoink extension:
"serviceName": "Add Selected Text to Yoink",
"description": "Add the selected text to Yoink."
popclip version: 3785
check installed: true
service name: Add Selected Text to Yoink
capture html: true
description: Add the selected text to Yoink.
Not all of those fields are strictly needed. As we have already seen in Snippets, we can also express a similar extension very minimally, at the loss of some of the niceties that the fleshed-out version provides:
"serviceName": "Add Selected Text to Yoink"
service name: Add Selected Text to Yoink
Minimal or maximal?
In general, if you're writing an extension for your own use, you can freely omit any fields that you don't need. But if you're preparing an extension for publication, you should flesh out the config as much as possible, to provide the best user experience for your extension.
Top level properties
The following keys are used at the top level of the config to define properties of the extension itself. All properties are optional except
|A short, human-readable display name for this extension.
|See Icons. If you omit this field, the icon for the first action will be used (if any), or else no icon will be displayed.
|You may provide a string to uniquely identify this extension. See The
|A short, human readable description of this extension. Appears in the directory but not in the app.
|Minimum version number of Mac OS X needed by this extension. For example
|Minimum PopClip version required. This is the integer build number e.g.
4151. Specifying the current PopClip version here can help preserve your extension's functionality in future, because PopClip applies backward-compatibility rules for old extensions.
|Array of dictionaries defining the options for this extension, if any. See The
|Title to appear at the top of the options window. Default is
Options for <extension name>.
network (allows use of XMLHttpRequest) and
dynamic (allows dynamically generated actions).
|Dictionary or Array
|A dictionary or array of dictionaries defining the action(s) for this extension. See Actions.
An identifier may contain only alphanumeric characters (
0-9), period (
.), and hyphen (
A good identifier should be globally unique so as not to clash with other creators. Use your own prefix, which could be a reverse DNS-style prefix based on a domain name you control, such as
com.example.myextension. Alternatively, just pick something likely to be unique to you.
If you don't provide an
identifier, PopClip will identify the extension by the package directory name (e.g.
Name.popclipext) if it's a package extension, or the
name if it's a snippet.
The identifier prefix
com.pilotmoon. is reserved for signed extensions published by me. If you try to use it for your own extensions, you'll get an error.
Options are presented to the user in a preferences user interface window and are saved in PopClip's preferences on behalf of the extension. Options appear in the UI in the order they appear in the
options array. An option dictionary has the following structure.
|Identifying string for this option. This is passed to your script. The identifier will be downcased or upcased for AppleScript and Shell Script targets, respectively — see Script variables.
|One of the following:
string (text box for free text entry),
boolean (a check box),
multiple (pop-up box with multiple choice options),
heading (not actually an option, but serves as a heading in the prefs window) or
password (password entry field).
|The label to appear in the UI for this option.
|A longer description to appear in the UI to explain this option.
|This field specifies the default value of the option. If omitted,
string options default to the empty string,
boolean options default to
multiple options default to the top item in the list. A
password field may not have a default value.
|Array of strings representing the possible values for the multiple choice option.
|Array of "human friendly" strings corresponding to the multiple choice values. This is used only in the PopClip options UI, and is not passed to the script. If omitted, the option values themselves are shown.
|If true, the option field will be shown inset to the right of the label, instead of under it. Default is false.
boolean options only. Specify an icon to appear next to the check box.
Fields shown as "String (Localizable)" type may be either a string or a dictionary. If you supply a string, that string is always used. Alternatively, you can supply a dictionary mapping language codes to strings, and PopClip will display the string for the user's preferred language if possible, with fallback to the
en string, which is always required.
The following language codes are supported:
Language codes table
Example of localized string
en: My Extension
fr: Mon Extension
Null values in Plist
Plist does not have a native way to represent the
null value of JSON and YAML. Use
<false /> in a Plist where you would use
null in JSON or YAML.
Key name mapping
Some field names were different in older versions of PopClip. Others have alternative allowable spellings.
To preserve backwards compatibility, key names in the config are transformed as follows:
First, the naming convention is standardized to lowercase with spaces. For example,
Then, if the field name has the prefix
option(which were expected by older versions of PopClip), it is removed.
Finally, PopClip applies the following mapping:
Key name mapping table
|apple script call
|apple script file
|java script file
|mac os version
|pop clip version
|preserve image color
|required os version
|required software version
An old extension uses the key
Extension Image File to define its icon. PopClip will first standardize the case to
extension image file. Then it will remove the
extension prefix, leaving
image file. Then it will map this to