Search Entity Utilities - Admin Components

The @medusajs/dashboard/lib subpath exports the utilities that manage the registry of entities in the Medusa Admin's global search. Use them to add your custom entities to the search palette, or to override the entities that Medusa registers by default.

Code
1import {2  clearSearchEntities,3  defineSearchEntity,4  getSearchEntity,5  getSearchEntityNames,6  hasSearchEntity,7} from "@medusajs/dashboard/lib"

Apps and plugins register their entities from the file src/admin/search-entities.tsx. The Medusa Admin seeds the registry with its built-in commerce entities before it runs your registrations, so you can override a built-in entity by registering it again under the same name.

defineSearchEntity#

Registers or replaces a searchable entity in the Medusa Admin's global search. The entity's definition sets the group heading in the search palette, an optional keyboard shortcut, and how to turn a search result into a palette item.

src/admin/search-entities.tsx
1import { defineSearchEntity } from "@medusajs/dashboard/lib"2
3defineSearchEntity("organization", {4  groupLabel: "Organizations",5  shortcut: {6    keys: { Mac: ["G", "Z"] },7    label: "Go to Organizations",8    to: "/organizations",9  },10  transform: (org) => ({11    id: org.id,12    title: org.name,13    subtitle: org.billing_email,14    to: `/organizations/${org.id}`,15    value: `organization:${org.id}`,16  }),17})

Parameters#

clearSearchEntities#

Removes every registered search entity, including the commerce entities that Medusa registers by default. Call it before registering your own set when the default entities shouldn't appear in the Medusa Admin's search.

src/admin/search-entities.tsx
1import {2  clearSearchEntities,3  defineSearchEntity,4} from "@medusajs/dashboard/lib"5
6clearSearchEntities()7
8defineSearchEntity("brand", {9  groupLabel: "Brands",10  transform: (brand) => ({11    id: brand.id,12    title: brand.name,13    to: `/brands/${brand.id}`,14    value: `brand:${brand.id}`,15  }),16})

getSearchEntity#

Returns a registered entity's definition by its name.

Code
1import { getSearchEntity } from "@medusajs/dashboard/lib"2
3const definition = getSearchEntity("brand")

Parameters#

Returns#

Returns the SearchEntityDefinition, or undefined when no entity is registered under that name.

getSearchEntityNames#

Returns the names of the entities that can be searched, in registration order. Entities that only contribute a shortcut are left out, since there's nothing to query for them.

Code
1import {2  getSearchEntityNames,3} from "@medusajs/dashboard/lib"4
5const names = getSearchEntityNames()

Returns#

Returns a string[] of the searchable entities' names.

hasSearchEntity#

Returns whether a name is registered as a searchable entity. It returns false for entries that only contribute a shortcut.

Code
1import { hasSearchEntity } from "@medusajs/dashboard/lib"2
3if (hasSearchEntity("brand")) {4  // ...5}

Parameters#

Returns#

Returns a boolean that is true when the entity is registered and has a transform function.

Types#