Help

useComboboxData - Admin Components

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

The useComboboxData hook loads paginated and searchable options from the Medusa backend for a Combobox component. The Medusa Admin uses it in forms where the user selects a record, such as a product's collection or a region's countries.

Code
import { useComboboxData } from "@medusajs/dashboard/hooks"

Example#

Pass the hook's returned properties to the Combobox component:

Code
1import { Combobox } from "@medusajs/dashboard/components"2import { useComboboxData } from "@medusajs/dashboard/hooks"3import { sdk } from "../lib/sdk"4
5const CollectionSelect = ({ value, onChange }) => {6  const collections = useComboboxData({7    queryKey: ["product_collections"],8    queryFn: (params) =>9      sdk.admin.productCollection.list(params),10    getOptions: (data) =>11      data.collections.map((collection) => ({12        label: collection.title,13        value: collection.id,14      })),15  })16
17  return (18    <Combobox19      value={value}20      onChange={onChange}21      options={collections.options}22      searchValue={collections.searchValue}23      onSearchValueChange={24        collections.onSearchValueChange25      }26      fetchNextPage={collections.fetchNextPage}27      disabled={collections.disabled}28    />29  )30}

The hook debounces the search value before sending the q query parameter to the Medusa backend, and it loads the next page of options when fetchNextPage is called.

To keep a record that the form already selected in the list, pass its ID to defaultValue or selectedValue. The hook then fetches that record separately and adds it to the beginning of options, even when the current page doesn't include it.

Parameters#

The hook accepts an object with the following properties:

queryKeyQueryKey

Required. The TanStack Query key that the hook uses as the base for its queries. The hook appends the search query and the default or selected value to it.

queryFn(params) => Promise<TResponse>

Required. A function that fetches the options from the Medusa backend. It receives an object that may have the id, q, offset, and limit query parameters, and it must resolve to a response that has the offset, limit, and count properties.

getOptions(data: TResponse) => TOption[]

Required. A function that transforms a page of the response into an array of options. Each option has a label and a value.

defaultValuestring | string[]

The value or values that the hook must always include in the returned options. The hook fetches them in a separate query and adds them to the beginning of options when the user hasn't typed a search value.

defaultValueKeykeyof TParams

The query parameter that the hook uses to fetch the defaultValue. The default value is id.

selectedValuestring

The ID of the currently selected record. The hook fetches it in a separate query and adds it to the beginning of options so that the selection stays visible while the user searches or paginates.

pageSizenumber

The number of options to fetch per page. The default value is 10.

enabledboolean

Whether the hook sends its queries. Set it to false to defer loading, for example until another field has a value. The default value is true.

Returns#

Along with the following, the hook returns the rest of TanStack Query's useInfiniteQuery result.

optionsTOption[]

The options of all loaded pages, including the default and selected values. Pass it to the options prop of the Combobox component.

searchValuestring

The current value of the search input before debouncing.

onSearchValueChange(value: string) => void

A function that changes the search value. The hook debounces it for 300 milliseconds before it refetches the options.

disabledboolean

Whether the combobox has no data to search in. It's true when enabled is false, or when the first request resolved with no options and the user hasn't typed a search value.

Was this page helpful?