# Open URL actions

In an Open URL action, PopClip will ask macOS to open a URL generated from a template that you provide.

If the URL scheme is `http:` or `https:` and the current app is a [known browser](https://www.popclip.app/kb/browsers.md), PopClip will ask
the current app to open the URL.

In all other cases, PopClip will ask macOS to open the URL in the default app app for its URL scheme.

**Tip: Opening a URL from JavaScript**

You can also use
[`popclip.openUrl()`](https://www.popclip.app/dev/api/interfaces/PopClip.html#openurl)
within a [JavaScript action](https://www.popclip.app/dev/js-actions.md).

## Properties

An Open URL action is defined by the presence of a `url` field, plus additional
optional fields, as follows:

| Key            | Type               | Description                                                                                                                                                  |
| -------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `url`          | String             | The URL to open when the user clicks the action. Use either `{popclip text}` or `***` as placeholder for the selected text.                                  |
| `cleanQuery`   | Boolean (Optional) | If `true`, newlines and tabs in the text will be replaced with a space, and consecutive spaces will be collapsed to a single space. Default is `false`.      |
| `spacesAsPlus` | Boolean (Optional) | If `true`, spaces in the inserted text are encoded as `+` instead of `%20`. Some search engines (for example Amazon) expect this format. Default is `false`. |

**Note: Verbatim search with the Option key**

If the user holds Option (⌥) when invoking the action, PopClip wraps the
inserted text in double quotes, so that search engines treat it as an
exact-phrase search.

_The `alternateUrl` property supported by earlier versions of PopClip was
removed in PopClip 2026.7. If present in a config, it is now ignored._

## Input and output

The selected plain text will be inserted into the URL, replacing the
`{popclip text}` or `***` placeholder if present. PopClip will always trim leading and
trailing whitespace and newlines, and URL-encode the text. Optionally, PopClip
will perform further whitespace cleanup with the `cleanQuery` flag.

Option parameters can be inserted in the URL, in the same format as for
AppleScript actions. See [example](#use-of-option-parameter).

URL actions never return any output.

**Tip: Advanced behaviours**

If a plain Open URL action isn't enough, use a [JavaScript action](https://www.popclip.app/dev/js-actions.md). There are two functions:

- [`popclip.openUrl()`](https://www.popclip.app/dev/api/interfaces/PopClip.html#openurl) opens a URL you have built yourself.
- [`popclip.openTemplateUrl()`](https://www.popclip.app/dev/api/interfaces/PopClip.html#opentemplateurl) takes the same `***` placeholder as the `url` property and does the encoding for you.

```javascript
await popclip.openTemplateUrl(
  "https://example.com/?q=***",
  popclip.input.text,
  {
    app: "com.google.Chrome",
  },
);
```

Both take the same options, and both return a promise that resolves once the URL has been handed to the browser.

## Examples

### Simple web search

The following snippet defines an extension with a single URL action that opens a
search for the selected text on the movie review site, Rotten Tomatoes:

```yaml
#popclip extension to search Rotten Tomatoes
name: Rotten Tomatoes
icon: iconify:simple-icons:rottentomatoes
url: https://www.rottentomatoes.com/search?search=***
```

### Custom URL scheme

The following snippet opens a custom URL scheme, in this case `maps:` for Apple
Maps:

```yaml
#popclip custom URL scheme example, Apple Maps
name: Maps
icon: iconify:material-symbols:map-outline
url: maps://?q={popclip text}
```

### Use of option parameter

The following snippet opens a Wiktionary search page, with the site domain
specified as an option parameter:

```yaml
#popclip Wiktionary search with subdomain option
name: Wiktionary
icon: iconify:ooui:logo-wiktionary
url: https://{popclip option subdomain}.wiktionary.org/wiki/{popclip text}
options:
  - type: string
    identifier: subdomain
    label: Site subdomain
    defaultValue: en
```

```json
#popclip Wiktionary search with subdomain option
{
  "name": "Wiktionary",
  "icon": "iconify:ooui:logo-wiktionary",
  "url": "https://{popclip option subdomain}.wiktionary.org/wiki/{popclip text}",
  "options": [
    {
      "type": "string",
      "identifier": "subdomain",
      "label": "Site subdomain",
      "defaultValue": "en"
    }
  ]
}
```