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 a url key in the options argument.

Examples

Example 1: Static array of records

window.CommandBar.addRecords(
"users",
[
{ name: "Jane", id: 1 },
{ name: "Jill", id: 2 },
{ name: "Jack", id: 3 },
],
{
labelKey: "name",
recordOptions: {
url: "/{{record.name}}",
},
}
);

Example 2: Add records "lazily" with a loader function

// ** Recommended **

// - Loader is called each time Spotlight opens
// - Filtering when a user types in Spotlight is handled automatically by Command AI
window.CommandBar.addRecords(
"users",
[], // call once with an empty array to prevent fetch on first page load
{
recordOptions: {
url: "/{{record.id}}",
},
}
);
window.CommandBar.addRecords("users", fetchUsersLoader, {
recordOptions: {
url: "/{{record.id}}",
},
});

Example 3: 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(`https://yourapi.com/search?=${query}`);

return response.json();
};
// Register search function to Command AI
window.CommandBar.addRecords("contacts", [], {
onInputChange: onSearchContacts,
recordOptions: {
url: "/{{record.id}}",
},
});

Example 4: Add a custom component content preview

// See `.addComponent` for the full example
window.CommandBar.addRecords(
"pets",
[
{
label: "Fido",
id: "foo42",
photo: "https://www.example.com/img/fido.jpg",
},
{
label: "Buster",
id: "bar43",
photo: "https://www.example.com/img/buster.jpg",
},
{
label: "Brutus",
id: "baz44",
photo: "https://www.example.com/img/brutus.jpg",
},
],
{
content: { type: "component", value: "record-preview-with-image" },
recordOptions: {
url: "/{{record.id}}",
},
}
);

Method parameters

key Required

string

Key for the record.

initialValue Required

any | function

The initial value of key for the record.

Special reserved fields for arrays of objects

PropertyTypeDescription
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

object

Options to customize properties for key.

PropertyTypeDescription
onInputChangefunction | async functionAdds a custom search function to Command AI 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 Command AI. 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.

recordOptions

PropertyTypeDescription
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.

content

PropertyTypeDescription
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.