Help

Combobox - Admin Components

Note: This component is available since Medusa v2.21.0.

The Combobox component is a select input with search, multi-select, pagination, and the option to create new values. The Medusa Admin uses it in forms where the user chooses records loaded from the Medusa backend, such as a product's collection or a region's payment providers.

Code
import { Combobox } from "@medusajs/dashboard/components"

Example#

Pair Combobox with the useComboboxData hook to load the options from the Medusa backend and paginate them as the user scrolls:

Code
import { Combobox, Form } from "@medusajs/dashboard/components"
import { useComboboxData } from "@medusajs/dashboard/hooks"
import { sdk } from "../lib/sdk"

const CollectionField = ({ control }) => {
  const collections = useComboboxData({
    queryKey: ["product_collections"],
    queryFn: (params) =>
      sdk.admin.productCollection.list(params),
    getOptions: (data) =>
      data.collections.map((collection) => ({
        label: collection.title,
        value: collection.id,
      })),
  })

  return (
    <Form.Field
      control={control}
      name="collection_id"
      render={({ field }) => (
        <Form.Item>
          <Form.Label>Collection</Form.Label>
          <Form.Control>
            <Combobox
              {...field}
              options={collections.options}
              searchValue={collections.searchValue}
              onSearchValueChange={
                collections.onSearchValueChange
              }
              fetchNextPage={collections.fetchNextPage}
              disabled={collections.disabled}
            />
          </Form.Control>
          <Form.ErrorMessage />
        </Form.Item>
      )}
    />
  )
}

To let the user select multiple values, pass an array as the value prop. The onChange function then receives an array of the selected values.

Props#

Aside from the HTML props of an input element, Combobox accepts the following props:

optionsobject[]

The options the user can select from. This is the only required prop.

valuestring | string[]Optional

The selected value. Pass an array to allow selecting multiple values. If you don't pass this prop, the component manages the value internally.

onChange(value?: string | string[]) => voidOptional

The function to execute when the user selects or removes a value.

searchValuestringOptional

The search query. Pass it when you filter the options yourself, such as when you load them from the Medusa backend. Otherwise, the component filters and sorts the options for you.

onSearchValueChange(value: string) => voidOptional

The function to execute when the user changes the search query.

fetchNextPage() => voidOptional

The function to execute when the user scrolls to the end of the options list. Use it to load the next page of options.

isFetchingNextPagebooleanOptional

Whether the next page of options is loading. The component shows a loading placeholder at the end of the list.

onCreateOption(value: string) => voidOptional

The function to execute when the user creates an option from the search query. Pass it to show a create option in the list.

shouldAlwaysShowCreateOptionbooleanOptional

Whether to show the create option even when the search query matches existing options.

noResultsPlaceholderReact.ReactNodeOptional

The content to show when there are no options and the user hasn't typed a search query.

allowClearbooleanOptional

Whether to show a button that clears the selected value.

forceHideInputbooleanOptional

Whether to always hide the search input. Use it for selects whose options the user doesn't need to search.

displayMode"count" | "chips"Optional

How to display multiple selected values. count shows the number of selected values, and chips shows a badge for each value.

Default: count

placeholderstringOptional

The placeholder to show when the user hasn't selected a value.

Was this page helpful?