CMD Bar Search

Learn how to make your product searchable

The Stepsailor Command Bar includes a powerful search interface. This allows users to explore and navigate your product—without consuming AI tokens—by searching through relevant resources like users, documents, or internal tools.

With just a few lines of code, you can define these searchable resources and plug them into the command bar.

Command Bar Search example

---

🔍 What Are Searchable Resources?

Searchable resources are entries (e.g., users, documents, knowledge bases) that are indexed and shown in the Command Bar’s search view. These resources:

• Do not consume AI tokens

• Can be cached

• Are searchable via a provided function

• Are displayed with a customized UI (title, image, etc.)

---

🧱 Defining a Resource

To define a resource, use the defineResource method on the CommandBar API instance.

Basic Example

cmdBar.defineResource({
  typeName: 'User',
  name: 'User',
  schema: z.object({
    id: z.number(),
    name: z.string(),
    email: z.string(),
  }),
  searchable: {
    searchFunction: async (query) => {
      // Here you are connecting the Resource with the database
      return users.filter((user) =>
        user.name.toLowerCase().includes(query.toLowerCase())
      );
    },
    mapToDisplay: (resource) => ({
      title: resource.name,
      imageUrl: `https://picsum.photos/seed/${resource.id}/200/300`,
      onClick: () => navigateTo(`/users/${resource.id}`);
    }),
  },
});

---

⚙️ Searchable Options

When adding the searchable field to your resource, here are the key options:

Option	Type	Description	Default
searchFunction	(query: string) => Promise<Data[]>	Function to return matching results	—
mentionable	boolean	If resource can be used with @mention syntax	false
visibleInCommandBarSearch	boolean	Whether to show in search results	true
maxResults	number	Max number of results to return	5
debounceTime	number	Debounce time in ms	300
cache	ResourceCacheConfig	Helps reduce backend load	undefined
listPriority	number	Higher priority = top of search list	0
searchCategory	string	Group name shown in UI	name field
mapToDisplay	(resource) => { title, imageUrl, ... }	UI presentation config	Required

Example with Caching and Display Customization

cmdBar.defineResource({
  typeName: 'KnowledgeBase',
  name: 'Knowledge Base',
  schema: z.object({
    id: z.number(),
    name: z.string(),
  }),
  searchable: {
    cache: { ttl: 1000 * 60 * 5 },
    searchFunction: async (query) => {
      return knowledgeBases.filter((kb) =>
        kb.name.toLowerCase().includes(query.toLowerCase())
      );
    },
    mapToDisplay: (resource) => ({
      title: resource.name,
      imageUrl: `https://fakeimg.pl/250x250/9effe8?text=${resource.name[0].toUpperCase()}`,
      onClick() {
        console.log('Selected:', resource);
      },
    }),
  },
});

---

🧠 Tips

• Define the smallest meaningful schema. Only expose fields you want to use/display.

• mapToDisplay is used to control how the search results are displayed

• Use caching for high-traffic queries to improve performance.