PopClip JavaScript API Reference
    Preparing search index...

    Interface Extension<CustomOptions>

    The Extension object defines the PopClip extension.

    interface Extension<CustomOptions = Options> {
        action?: Action<CustomOptions> | ActionFunction<CustomOptions>;
        actions?:
            | PopulationFunction<CustomOptions>
            | (Action<CustomOptions> | ActionFunction<CustomOptions>)[];
        after?: AfterStep;
        app?: AssociatedApp;
        auth?: AuthFunction;
        before?: BeforeStep;
        captureHtml?: boolean;
        captureRtf?: boolean;
        circle?: boolean;
        excludedApps?: string[];
        filled?: boolean;
        flipX?: boolean;
        flipY?: boolean;
        icon?: string | null;
        monospaced?: boolean;
        moveX?: number;
        moveY?: number;
        options?: readonly Option[];
        preserveAspect?: boolean;
        preserveColor?: boolean;
        regex?: string | RegExp;
        requiredApps?: string[];
        requirements?: (
            | Requirement
            | "!cut"
            | "!copy"
            | "!paste"
            | "!text"
            | "!url"
            | "!formatting"
            | "!isurl"
            | "!urls"
            | "!email"
            | "!emails"
            | "!path"
            | `!option-${string}=${string}`
        )[];
        restorePasteboard?: boolean;
        rotate?: number;
        scale?: number;
        search?: boolean;
        square?: boolean;
        stayVisible?: boolean;
        strike?: boolean;
        submenu?: | PopulationFunction<CustomOptions>
        | (Action<CustomOptions> | ActionFunction<CustomOptions>)[];
        test?: TestFunction;
        title?: LocalizableString;
    }

    Type Parameters

    Hierarchy (View Summary)

    Index
    action? actions? after? app? auth? before? captureHtml? captureRtf? circle? excludedApps? filled? flipX? flipY? icon? monospaced? moveX? moveY? options? preserveAspect? preserveColor? regex? requiredApps? requirements? restorePasteboard? rotate? scale? search? square? stayVisible? strike? submenu? test? title?
    action?: Action<CustomOptions> | ActionFunction<CustomOptions>

    Simplified property to define a single action.

    actions?:
        | PopulationFunction<CustomOptions>
        | (Action<CustomOptions> | ActionFunction<CustomOptions>)[]

    Define the actions to go in PopClip's popup. This can be an array or a function.

    • If it's an array, the supplied actions are used in the popup, subject to meeting the requirements and regex conditions.

    • If it's a population function, it is called by PopClip to dynamically populate the popup with actions from this extension. Setting requirements and regex keys has no effect on dynamic actions — the function itself is responsible for deciding what actions to show. Population function requires the dynamic entitlement.

    after?: AfterStep

    An optional step to perform after the main action.

    app?: AssociatedApp

    Declares the application or website associated with this action, if any.

    auth?: AuthFunction

    If you define this function then PopClip will display a 'sign in' button in the options UI. When the user clicks the button, PopClip will call this function with an info object and a flow callback.

    If the sign in needs a username and password, you'll also need to define username and password options. PopClip will then pass the values of those options in the info parameter.

    before?: BeforeStep

    An optional step to perform before the main action.

    captureHtml?: boolean

    Whether PopClip will capture HTML and Markdown content for the selection. Default is no.

    captureRtf?: boolean

    Whether PopClip will capture RTF (Rich Text Format) content for the selection. Default is no.

    circle?: boolean

    Draw the icon inside a circle.

    excludedApps?: string[]

    Array of bundle identifiers for which the extension should not appear. The action will not appear if PopClip is used in any of the specified apps.

    This property has no effect on dynamically generated actions.

    filled?: boolean

    Draw the enclosing shape as a solid shape.

    flipX?: boolean

    If true, the supplied icon will be drawn horizontally flipped. Default is false.

    flipY?: boolean

    If true, the supplied icon will be drawn vertically flipped. Default is false.

    icon?: string | null

    A string to define the action's icon.

    If no icon is defined here, the extension's icon will be used, if any. Setting to null explicitly sets the action to have no icon.

    monospaced?: boolean

    For text icons only. Draw the text using a monospaced font.

    moveX?: number

    Move the icon horizontally by the specified distance, expressed as percentage of the icon's width.

    moveY?: number

    Move the icon vertically by the specified distance, expressed as percentage of the icon's height.

    options?: readonly Option[]

    Defines the user-configurable options for this extension.

    preserveAspect?: boolean

    If true, the supplied icon will be displayed with its original aspect ratio instead of being scaled to fit a square. Default is false.

    preserveColor?: boolean

    If true, the supplied icon will be displayed with its original color instead of being filled in white/black. Default is false.

    regex?: string | RegExp

    A regular expression to decide whether this action appears in the popup.

    • If no regex is specified here, the action takes the value of Extension.regex.
    • If no regex is specified there either, the action will match any input.

    You may express the value either as a JavaScript regular expression literal (or otherwise constructed RegExp object), or as a string.

    • If you supply a RegExp it will be evaluated in the JavaScript engine.
    • If you supply a string it will be evaluated by macOS natively using the NSRegularExpression API (same as for 'classic' PopClip extensions).

    If the regex matches the selected text, the action will be shown in the popup and the first occurrence of the matched text is accessible later via matchedText.

    If there is no match, the action is excluded from the popup.

    The regex's lastIndex is reset before and after each invocation, so the g (global) and y (sticky) flags have no effect.

    This property has no effect on dynamically generated actions.

    regex = /abc/i   // Example regex 'abc' with 'i' (case insensitive) flag
                     // Matches abc, ABC, Abc, etc.
    requiredApps?: string[]

    Array of bundle identifiers for which the extension should appear. The action will only appear if PopClip is used in one of the specified apps.

    This property has no effect on dynamically generated actions.

    requirements?: (
        | Requirement
        | "!cut"
        | "!copy"
        | "!paste"
        | "!text"
        | "!url"
        | "!formatting"
        | "!isurl"
        | "!urls"
        | "!email"
        | "!emails"
        | "!path"
        | `!option-${string}=${string}`
    )[]

    An array of conditions which must be met for this action to appear — see Requirement.

    • If no array is specified here, the action takes the value of Extension.requirements.
    • If no array is specified there either, the action takes the default value ["text"].

    When multiple conditions are specified, all of them must be satisfied.

    An empty array ([]) indicates no requirements at all, meaning the action will always appear.

    This property has no effect on dynamically generated actions.

    restorePasteboard?: boolean

    Whether the pasteboard should be restored to its original state after paste-result.

    rotate?: number

    Rotate the icon anticlockwise by the specified angle, expressed in degrees.

    scale?: number

    Scale the icon by the specified factor, expressed as a percentage of the original size.

    search?: boolean

    Draw the icon inside a magnifying glass shape.

    square?: boolean

    Draw the icon inside a square.

    stayVisible?: boolean

    Whether PopClip's popup should stay on screen after clicking this action's button. Default is no.

    strike?: boolean

    Draw a strike-through line over the icon.

    submenu?:
        | PopulationFunction<CustomOptions>
        | (Action<CustomOptions> | ActionFunction<CustomOptions>)[]

    Makes the whole extension a single button that opens a submenu of child actions, as an alternative to actions/action. Same shape as Action.submenu: a static array of actions, or a population function (requires the dynamic entitlement).

    test?: TestFunction

    Exported test function for use during development.

    title?: LocalizableString

    The action's title.

    If no title is defined here, the extension's name will be used, if any.

    Settings
    Member Visibility

    On This Page
    Properties