Skip to main content

addRecords(key, initialValue, options?)

Adds a record. For any existing keys, updates values. To make the record show up in search, you must provide the url option or add at least one record action, either in the extension, the dashboard, or using .addRecordAction.


// Example 1: Static array of records
// - A recordAction must be added later for these to appear in Spotlight
window.CommandBar.addRecords("users", ["Jane", "Jill", "Jack"]);

// Example 2: Static array of records with recordAction `url` field to make a `Page` object
{ name: "Jane", id: 1 },
{ name: "Jill", id: 2 },
{ name: "Jack", id: 3 },
labelKey: "name",
recordOptions: {
url: '/{{}}'

// ** Recommended **
// Example 3: Add records "lazily" with a loader function
// - Loader is called each time Spotlight opens
// - Filtering when a user types in Spotlight is handled automatically by CommandBar
window.CommandBar.addRecords("users", []); // call once with an empty array to prevent fetch on first page load
window.CommandBar.addRecords("users", fetchUsersLoader);

// Example 4: Custom search function with no default Loader
// - Useful for setting your own filtering algo or when the number of records is very large (100,000+)
// - Search function will be called each time a user types to search (with debounce)
const onSearchContacts = async (query) => {
const response = fetch(`${query}`);

return response.json()
// Register search function to CommandBar
window.CommandBar.addRecords("contacts", [], {
onInputChange: onSearchContacts,

// Example 5: Add a custom component content preview
// See `.addComponent` for the full example
label: "Fido",
id: "foo42",
photo: "",
label: "Buster",
id: "bar43",
photo: "",
label: "Brutus",
id: "baz44",
photo: "",
content: { type: "component", value: "record-preview-with-image" },

Method parameters

key Required


Key for the record.

initialValue Required

any | function

The initial value of key for the record.

Special reserved fields for arrays of objects

categorystringUsed to visually group the list of values with others that have the same category value.
iconstringIcon to be shown next to each value. Can be a URL (absolute or relative), emoji character, or an SVG string (which must begin with <svg ). Specifying a .icon property will override any default set in options.renderOptions.defaultIcon.
__extraHTMLstringHTML to append to the bottom of the record. Useful for displaying rich information about the record, e.g. a profile picture or an additional view describing the record.



Options to customize properties for key.

onInputChangefunction | async functionAdds a custom search function to CommandBar for key. This custom search function should take as its first argument a string query and return an array of results. The function will be called whenever a user types in a scenario where they might be searching for key. Results from the custom search function should be filtered; they will not be filtered by CommandBar. This means that the search results will be identical to those returned by the function.
recordOptionsobjectOptions specific to searching for records.
searchableFieldsstring[]A list of object fields to be searched. If a custom searchFunction is provided, matches will be highlighted in these fields. Field names will be transformed from camelCase or snake_case into Sentence case.
labelKeystringThe value key of key objects you want to use to display the object's label.
descriptionKeystringThe value key of key objects you want to use to display the object's description (subtext under label).
defaultIconstringDefault icon to show alongside key objects. Can be a URL (absolute or relative) or emoji character. You can specify a custom icon for every object by setting an .icon field.
renderAs'list' | 'grid'If 'grid' is passed, render the records as a grid instead. Defaults to 'list'.
searchTabEnabledbooleanWhether to make the records available as a major category (tab). Defaults to false.
__imagestringImage to show when the command is displayed in a grid.
contentobject | array of objectsIf specified, show a preview for these records.


unfurlbooleanTurn on unfurling for key.
categoryNamestringThe category header name for key objects shown during search (not used if unfurl is on).
urlstringURL for a record entry, supports interpolation for record fields e.g. /{{record.slug}}. This option is a shorthand for adding a Page record action.


type RequiredstringEither 'html' or 'component'
value RequiredstringStatic HTML preview to show, a key of the current record object surrounded by curly braces (e.g. {{htmlContent}}), or the key of a custom component added with addComponent.