paletteProviders

Details #

A palette provider is a search box feature. While someone types in the command palette, Switchboard asks the provider for rows. The rows appear in the results list with the extension's name beside them. Choosing a row can run code.

Declare it in switchboard.json under adds.paletteProviders. Implement it with paletteProvider(id, { search, run }) from @switchboard/sdk and list the result under paletteProviders in defineExtension. The declaration and the code must match: an entry declared but not implemented (or the other way round) is refused when the extension loads.

{
  "adds": {
    "paletteProviders": [{ "id": "notes", "title": "Notes", "keyword": "n" }]
  }
}

import { defineExtension, paletteProvider } from '@switchboard/sdk';

export default defineExtension({
  paletteProviders: [
    paletteProvider('notes', {
      search: async (query, ctx) => [
        { id: 'new', title: `New note: ${query}`, subtitle: 'Notes', data: { text: query } },
      ],
      run: async (item, ctx) => { await ctx.notify({ title: 'Created', body: String(item.data) }); },
    }),
  ],
});

Gotchas #

• search has 2 seconds. A slow provider is skipped for that keystroke. Keep it fast and keep slow work for run.

• Only the first 8 rows are shown.

• run has 10 seconds.

• ctx.notify in the example needs "permissions": { "notifications": true }.

• Unknown keys in an entry are refused.

Handler #

search(query, ctx) gets the text typed. With a keyword, the query must start with the keyword and query is what follows it. Without a keyword, every query goes to the provider. It returns a list of rows.

A row has an id and a title, both required and not empty. It can also have a subtitle, an icon (an SF Symbol name) and data. A row without an id or title is dropped.

run(item, ctx) is optional. It runs when a row is chosen and gets that row back, with data as you returned it. Its result is ignored.

Full example #

The Full example above is a working extension, Quick Notes: type note call Sam in the palette to save a note, and pick a saved note to tick it off. You can download it from the Full example section and edit it into your own.

See also #

• actions