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

// 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
window.CommandBar.addRecords(
  "users",
  [
    { name: "Jane", id: 1 },
    { name: "Jill", id: 2 },
    { name: "Jack", id: 3 },
  ],
  {
    labelKey: "name",
    recordOptions: {
        url: '/{{record.name}}'
    }
  }
);

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

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