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
Property | Type | Description |
---|---|---|
category | string | Used to visually group the list of values with others that have the same category value. |
icon | string | Icon 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 . |
__extraHTML | string | HTML 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
.
Property | Type | Description |
---|---|---|
onInputChange | function | async function | Adds 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. |
recordOptions | object | Options specific to searching for records. |
searchableFields | string[] | 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. |
labelKey | string | The value key of key objects you want to use to display the object's label. |
descriptionKey | string | The value key of key objects you want to use to display the object's description (subtext under label). |
defaultIcon | string | Default 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' . |
searchTabEnabled | boolean | Whether to make the records available as a major category (tab). Defaults to false . |
__image | string | Image to show when the command is displayed in a grid. |
content | object | array of objects | If specified, show a preview for these records. |
recordOptions
Property | Type | Description |
---|---|---|
unfurl | boolean | Turn on unfurling for key . |
categoryName | string | The category header name for key objects shown during search (not used if unfurl is on). |
url | string | URL 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
Property | Type | Description |
---|---|---|
type Required | string | Either 'html' or 'component' |
value Required | string | Static 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. |