• Public
  • Public/Protected
  • All

PopClip JavaScript API Reference


Type aliases

ActionFunction<CustomOptions>: (input: Input, options: CustomOptions & AuthOptions, context: Context) => Promise<string | void> | string | void

Type parameters

Type declaration

    • An action function is called when the user clicks the action button in PopClip. This is where the extension does its main work.


      • input: Input

        The selected text and related properties. (Same object as [[PopClip.selection]].)

      • options: CustomOptions & AuthOptions

        Current values of the options for this extension. (Same object as PopClip.options.)

      • context: Context

        Information about the context surrounding the selection. (Same object as PopClip.context.)

      Returns Promise<string | void> | string | void

AfterStep: BeforeStep | "popclip-appear" | "show-status" | "copy-result" | "paste-result" | "show-result" | "preview-result"

Strings which can be used to specify the after action.

AuthFlowFunction: (url: string, params?: {}, expect?: string[]) => Promise<any>

Type declaration

    • (url: string, params?: {}, expect?: string[]): Promise<any>
    • Object returned by Extension.auth when there is an authentication flow to kick off


      • url: string
      • Optional params: {}
        • Optional expect: string[]

        Returns Promise<any>

    AuthFunction: (info: AuthInfo, flow: AuthFlowFunction) => Promise<string>

    Type declaration

    BeforeStep: "cut" | "copy" | "paste" | "paste-plain"

    Strings which can be used to specify the before action.

    LocalizableString: string | StringTable

    A type to represent a localizable string.


    The value may be either a string or an object. If you supply a string, that string is used. If you supply a StringTable object, PopClip will display the string for the user's preferred language if possible, with fallback to the en string.


    option.label = "Color" // just use this string
    option.label = { en: "Color", "en-GB": "Colour", fr: "Couleur", "zh-Hans": "颜色" }
    NegatedRequirement: `!${Requirement}`

    Negated form of Requirement.

    PopulationFunction<CustomOptions>: (input: Input, options: CustomOptions, context: Context) => (Action | ActionFunction)[] | Action | ActionFunction | void

    Type parameters

    Type declaration

    Requirement: "text" | "cut" | "paste" | "formatting" | "url" | "urls" | "email" | "emails" | "path" | `option-${string}=${string}`

    A requirement is specified in the Action.requirements array as a string.


    ["paste", "!urls", "option-goFishing=1"]


    • defineExtension<CustomOptions>(extension: Extension<CustomOptions>): void
    • This global function may be called as an alternative to setting module.exports directly. The advantage of using defineExtension() is that you will automatically get type checking and autocomplete for your extension object.

      You may define the shape of the extensions's options object by specifying the CustomOptions generic type parameter. This will enable type checking and autocomplete for the options parameter in action functions and the population function.

      Type parameters


      • extension: Extension<CustomOptions>

        The extension object to define.

      Returns void

    • print(...args: any[]): void
    • Output a string for debugging purposes. By default it is not output anywhere, but you can configure PopClip to output to the Console app by running the following command in Terminal:

      defaults write com.pilotmoon.popclip EnableExtensionDebug -bool YES

      then Quit and restart PopClip.


      print("Hello, world!")
      // print: Hello, world!
      print(1, Math.PI, 2/3, ['a','b','c'])
      // print: 1 3.141592653589793 0.6666666666666666 a,b,c


      • Rest ...args: any[]

      Returns void

    • require(file: string): object
    • Import an object from another file.


      PopClip's require() implementation attempts to import from the following module formats:

      • AMD modules, which use define(...).
      • CommonJS modules, which use module.exports = ... or exports.name = ...
      • TypeScript-compiled ES modules, which use exports.default = ...


      Paths beginning with ./ or ../ are resolved relative to the the location of the current file.

      Otherwise, the path is resolved relative to the extensions's package root. If there is no file in the extension, PopClip will look in its internal module repository.

      If no file extension is given, PopCLip will try adding the extensions .js, .ts, .json in that order.

      TypeScript files are transpiled to JavaScript on the fly.

      JSON files are parsed and returned as an object.å


      • file: string

        Path to the file to import.

      Returns object

      The imported object.

    • sleep(durationMilliseconds: number): Promise<void>
    • A promise-based sleep function. Included as a more convenient alternative to [[setTimeout]] for performing simple delays. Call as await sleep(1000).


      • durationMilliseconds: number

        How long to sleep in milliseconds

      Returns Promise<void>


    pasteboard: Pasteboard

    The global pasteboard object provides access to the contents of the macOS general pasteboard (i.e. the system clipboard). It implements Pasteboard.

    popclip: PopClip

    The global popclip object encapsulates the user's current interaction with PopClip, and provides methods for performing various actions. It implements PopClip.

    util: Util

    The global util object acts as a container for various utility functions and constants. It implements Util.

    Generated using TypeDoc