Search Engine Management

Glide Browser allows you to add custom search engines programmatically, giving you quick access to any search service directly from the address bar.

Adding a Search Engine

Use the glide.search_engines.add() API to register custom search engines:

await glide.search_engines.add({
  name: "Discogs",
  keyword: "disc",
  search_url: "https://www.discogs.com/search/?q={searchTerms}",
  favicon_url: "https://www.discogs.com/favicon.ico",
});

Now you can search Discogs by typing disc <query> in the address bar.

Search Engine Configuration

The configuration format matches the WebExtension chrome_settings_overrides.search_provider manifest specification.

Required Properties

name

string

required

The display name of the search engine

search_url

string

required

The URL to use for searches. Must contain {searchTerms} as a placeholder for the search query.

Optional Properties

keyword

string | string[]

Keyword(s) to trigger this search engine. Can be a single string or array of strings.

keyword: "@wiki"           // Single keyword
keyword: ["@w", "@wiki"]  // Multiple keywords

suggest_url

string

URL for search suggestions. Must contain {searchTerms} placeholder.

suggest_url: "https://example.com/suggest?q={searchTerms}"

favicon_url

string

URL to the search engine’s favicon

is_default

boolean

Set this search engine as the default. Queries without a keyword will use this engine.

is_default: true

search_url_get_params

string

Additional GET parameters for the search URL

search_url: "https://example.com/search",
search_url_get_params: "q={searchTerms}&format=json&lang=en"
// Results in: https://example.com/search?q=<query>&format=json&lang=en

search_url_post_params

string

Use POST method instead of GET, with these parameters in the request body

search_url: "https://example.com/search",
search_url_post_params: "q={searchTerms}&format=json"

suggest_url_get_params

string

Additional GET parameters for the suggestion URL

suggest_url: "https://example.com/suggest",
suggest_url_get_params: "q={searchTerms}&type=json"

Examples

Basic Search Engine

await glide.search_engines.add({
  name: "GitHub",
  keyword: "gh",
  search_url: "https://github.com/search?q={searchTerms}",
});

Usage: Type gh glide browser in the address bar

With Suggestions

await glide.search_engines.add({
  name: "DuckDuckGo",
  keyword: "ddg",
  search_url: "https://duckduckgo.com/?q={searchTerms}",
  suggest_url: "https://duckduckgo.com/ac/?q={searchTerms}",
  favicon_url: "https://duckduckgo.com/favicon.ico",
});

Multiple Keywords

await glide.search_engines.add({
  name: "Wikipedia",
  keyword: ["@wiki", "@w", "wiki"],
  search_url: "https://en.wikipedia.org/wiki/Special:Search?search={searchTerms}",
  suggest_url: "https://en.wikipedia.org/w/api.php?action=opensearch&search={searchTerms}",
});

Usage: Any of these will work:

@wiki quantum physics
@w quantum physics
wiki quantum physics

Default Search Engine

await glide.search_engines.add({
  name: "Brave Search",
  keyword: "brave",
  search_url: "https://search.brave.com/search?q={searchTerms}",
  suggest_url: "https://search.brave.com/api/suggest?q={searchTerms}",
  is_default: true,
});

Now typing a query without a keyword will use Brave Search.

POST Method Search

await glide.search_engines.add({
  name: "API Search",
  keyword: "api",
  search_url: "https://api.example.com/search",
  search_url_post_params: "q={searchTerms}&format=json&key=secret",
});

GET Parameters

await glide.search_engines.add({
  name: "YouTube",
  keyword: "yt",
  search_url: "https://www.youtube.com/results",
  search_url_get_params: "search_query={searchTerms}&sp=CAI%253D",
});
// Results in: https://www.youtube.com/results?search_query=<query>&sp=CAI%253D

Dynamic Search Engines

Add search engines conditionally based on context:

// Add different search engines based on OS
if (glide.ctx.os === "macosx") {
  await glide.search_engines.add({
    name: "macOS Apps",
    keyword: "app",
    search_url: "https://apps.apple.com/search?term={searchTerms}",
  });
}

// Add based on environment variable
const apiKey = glide.env.get("SEARCH_API_KEY");
if (apiKey) {
  await glide.search_engines.add({
    name: "Private API",
    keyword: "priv",
    search_url: `https://api.example.com/search?key=${apiKey}&q={searchTerms}`,
  });
}

Managing Search Engines

Updating an Existing Engine

Calling glide.search_engines.add() with an existing name will update it:

// Initial configuration
await glide.search_engines.add({
  name: "Example",
  keyword: "@old",
  search_url: "https://old.example.com/search?q={searchTerms}",
});

// Update it (same name)
await glide.search_engines.add({
  name: "Example",  // Same name = update
  keyword: "@new",
  search_url: "https://new.example.com/search?q={searchTerms}",
});
// Old keyword and URL are replaced

Removing Search Engines

Search engines added via the API are not automatically removed when you remove the code. You must manually remove them through Firefox’s preferences at about:preferences#search.

Best Practices

Use ConfigLoaded Autocmd

glide.autocmds.create("ConfigLoaded", async () => {
  await glide.search_engines.add({
    name: "My Search",
    keyword: "ms",
    search_url: "https://example.com/search?q={searchTerms}",
  });
});

Organize Multiple Engines

const searchEngines = [
  {
    name: "GitHub",
    keyword: "gh",
    search_url: "https://github.com/search?q={searchTerms}",
  },
  {
    name: "Stack Overflow",
    keyword: "so",
    search_url: "https://stackoverflow.com/search?q={searchTerms}",
  },
  {
    name: "npm",
    keyword: "npm",
    search_url: "https://www.npmjs.com/search?q={searchTerms}",
  },
];

glide.autocmds.create("ConfigLoaded", async () => {
  for (const engine of searchEngines) {
    await glide.search_engines.add(engine);
  }
});

Site-Specific Search Shortcuts

Create shortcuts for searching within specific sites:

const siteSearches = [
  { name: "Reddit", keyword: "r", domain: "reddit.com" },
  { name: "MDN", keyword: "mdn", domain: "developer.mozilla.org" },
  { name: "Rust Docs", keyword: "rust", domain: "doc.rust-lang.org" },
];

glide.autocmds.create("ConfigLoaded", async () => {
  for (const { name, keyword, domain } of siteSearches) {
    await glide.search_engines.add({
      name,
      keyword,
      search_url: `https://www.google.com/search?q=site:${domain}+{searchTerms}`,
    });
  }
});

Common Search Engines

Here are some popular search engines ready to use:

await glide.search_engines.add({
  name: "MDN",
  keyword: "mdn",
  search_url: "https://developer.mozilla.org/en-US/search?q={searchTerms}",
});

await glide.search_engines.add({
  name: "Stack Overflow",
  keyword: "so",
  search_url: "https://stackoverflow.com/search?q={searchTerms}",
});

await glide.search_engines.add({
  name: "GitHub",
  keyword: "gh",
  search_url: "https://github.com/search?q={searchTerms}",
});

Troubleshooting

Search engine not appearing

Make sure:

The code is inside a ConfigLoaded autocmd
You’ve reloaded the config with :config_reload
The name is unique
The search_url contains {searchTerms}

Keyword not working

Check that another search engine isn’t using the same keyword
Keywords are case-sensitive
Try using @ prefix to avoid conflicts: @gh instead of gh

Suggestions not showing

Ensure suggest_url contains {searchTerms}
Check browser console for CORS errors
Not all search APIs support CORS from browser context

The search engine API is defined in glide.d.ts:778-804. Test examples can be found in test/search/browser_search_engines.ts:33-312.

Reference

WebExtension Search Provider API
Source: browser-api.mts (search engine implementation)
Tests: test/search/browser_search_engines.ts

Get Started

Core Concepts

Guides

Features

Search Engine Management

Adding a Search Engine

Search Engine Configuration

Required Properties

Optional Properties

Examples

Basic Search Engine

With Suggestions

Multiple Keywords

Default Search Engine

POST Method Search

GET Parameters

Dynamic Search Engines

Managing Search Engines

Updating an Existing Engine

Removing Search Engines

Best Practices

Use ConfigLoaded Autocmd

Organize Multiple Engines

Site-Specific Search Shortcuts

Common Search Engines

Troubleshooting

Reference

Get Started

Core Concepts

Guides

Features

​Adding a Search Engine

​Search Engine Configuration

​Required Properties

​Optional Properties

​Examples

​Basic Search Engine

​With Suggestions

​Multiple Keywords

​Default Search Engine

​POST Method Search

​GET Parameters

​Dynamic Search Engines

​Managing Search Engines

​Updating an Existing Engine

​Removing Search Engines

​Best Practices

​Use ConfigLoaded Autocmd

​Organize Multiple Engines

​Site-Specific Search Shortcuts

​Common Search Engines

​Troubleshooting

​Reference

Adding a Search Engine

Search Engine Configuration

Required Properties

Optional Properties

Examples

Basic Search Engine

With Suggestions

Multiple Keywords

Default Search Engine

POST Method Search

GET Parameters

Dynamic Search Engines

Managing Search Engines

Updating an Existing Engine

Removing Search Engines

Best Practices

Use ConfigLoaded Autocmd

Organize Multiple Engines

Site-Specific Search Shortcuts

Common Search Engines

Troubleshooting

Reference