Skip to main content
useSelect hook is used to fetch data from the dataProvider and return the options for select boxes. It uses getList method as query function from the dataProvider.

​
Usage

import { useSelect } from "@refinedev/core";

const { options, onSearch } = useSelect({
  resource: "categories",
});

​
Props

​
resource
string
required
Resource name for API data interactions.
​
optionLabel
string | (item: TData) => string
Set the option’s label value. If a function is provided, it will be called with the item as argument.Default: "title"
// Using string
optionLabel: "name"

// Using function
optionLabel: (item) => `${item.firstName} ${item.lastName}`
​
optionValue
string | (item: TData) => string
Set the option’s value. If a function is provided, it will be called with the item as argument.Default: "id"
// Using string
optionValue: "id"

// Using function
optionValue: (item) => item.uuid
​
searchField
string
Field name to search for. If optionLabel is a string, uses optionLabel’s value.Default: "title" (or value of optionLabel if it’s a string)
// When optionLabel is string
useSelect({ optionLabel: "name" }) // uses "name" field

// When optionLabel is function
useSelect({ optionLabel: (item) => item.description }) // uses "title"

// Custom searchField
useSelect({ 
  optionLabel: (item) => item.description,
  searchField: "description"
})
​
sorters
CrudSort[]
Allows sorting the options.
sorters: [
  {
    field: "name",
    order: "asc",
  },
]
​
filters
CrudFilter[]
Allows filtering the options.
filters: [
  {
    field: "isActive",
    operator: "eq",
    value: true,
  },
]
​
defaultValue
BaseKey | BaseKey[]
Adds extra options by fetching with useMany. Useful for pre-populating select with selected values.
// Single value
defaultValue: "1"

// Multiple values
defaultValue: ["1", "2", "3"]
​
selectedOptionsOrder
'in-place' | 'selected-first'
Determines the order of selected options in the options array.Default: "in-place"
  • "in-place": Selected options appear in their original position
  • "selected-first": Selected options appear at the beginning
​
debounce
number
The number of milliseconds to delay search.Default: 300
​
queryOptions
UseQueryOptions
react-query’s useQuery options.
​
pagination
object
Pagination configuration.
​
pagination.currentPage
number
Current page index.
​
pagination.pageSize
number
default:"10"
Number of items per page.
​
pagination.mode
'server' | 'off'
default:"off"
Whether to use server side pagination or not.
​
defaultValueQueryOptions
UseQueryOptions
react-query’s useQuery options for the useMany query that fetches default values.
​
onSearch
(value: string) => CrudFilter[]
If defined, this callback allows you to override all filters for every search request.
onSearch: (value) => [
  {
    field: "name",
    operator: "contains",
    value,
  },
  {
    field: "description",
    operator: "contains",
    value,
  },
]
​
meta
MetaQuery
Additional meta data to pass to the dataProvider’s getList and getMany.
​
dataProviderName
string
If there is more than one dataProvider, you should use the dataProviderName that you will use.Default: "default"
​
successNotification
OpenNotificationParams | false
Notification configuration for successful queries.
​
errorNotification
OpenNotificationParams | false
Notification configuration for failed queries.
​
liveMode
'auto' | 'manual' | 'off'
Whether to update data automatically or manually if a related live event is received.
​
onLiveEvent
(event: LiveEvent) => void
Callback to handle live events.
​
liveParams
object
Additional params to pass to liveProvider’s subscribe method.
​
overtimeOptions
object
Loading overtime configuration.
​
overtimeOptions.interval
number
default:"1000"
Interval in milliseconds.
​
overtimeOptions.onInterval
(elapsedTime: number) => void
Callback to handle interval events.

​
Return Values

​
options
BaseOption[]
Array of options to be used in select component.
type BaseOption = {
  label: string;
  value: string;
};

const { options } = useSelect({ resource: "categories" });

console.log(options);
// [
//   { label: "Technology", value: "1" },
//   { label: "Science", value: "2" },
//   { label: "Sports", value: "3" },
// ]
​
onSearch
(value: string) => void
A function to trigger search. Debounced based on debounce prop.
const { onSearch } = useSelect({ resource: "categories" });

<input onChange={(e) => onSearch(e.target.value)} />
​
query
QueryObserverResult<GetListResponse<TData>, TError>
Result of the react-query’s useQuery for the list data.
​
defaultValueQuery
UseManyReturnType<TData, TError>
Result of the useMany hook for fetching default values.
​
overtime
object
Overtime loading information.
​
overtime.elapsedTime
number
Elapsed time in milliseconds.

​
Example

​
Basic Usage

import { useSelect } from "@refinedev/core";

const PostCreate = () => {
  const { options } = useSelect({
    resource: "categories",
  });

  return (
    <select>
      {options.map((option) => (
        <option key={option.value} value={option.value}>
          {option.label}
        </option>
      ))}
    </select>
  );
};

import { useSelect } from "@refinedev/core";

const PostCreate = () => {
  const { options, onSearch } = useSelect({
    resource: "categories",
    debounce: 500,
  });

  return (
    <div>
      <input
        type="text"
        placeholder="Search categories..."
        onChange={(e) => onSearch(e.target.value)}
      />
      
      <select>
        {options.map((option) => (
          <option key={option.value} value={option.value}>
            {option.label}
          </option>
        ))}
      </select>
    </div>
  );
};

​
Custom Label and Value

import { useSelect } from "@refinedev/core";

const PostCreate = () => {
  const { options } = useSelect({
    resource: "users",
    optionLabel: "fullName",
    optionValue: "userId",
  });

  return (
    <select>
      {options.map((option) => (
        <option key={option.value} value={option.value}>
          {option.label}
        </option>
      ))}
    </select>
  );
};

​
Using Label Function

import { useSelect } from "@refinedev/core";

const PostCreate = () => {
  const { options } = useSelect({
    resource: "users",
    optionLabel: (user) => `${user.firstName} ${user.lastName} (${user.email})`,
    optionValue: "id",
  });

  return (
    <select>
      {options.map((option) => (
        <option key={option.value} value={option.value}>
          {option.label}
        </option>
      ))}
    </select>
  );
};

​
With Default Values

import { useSelect } from "@refinedev/core";

const PostEdit = () => {
  const { options } = useSelect({
    resource: "categories",
    defaultValue: ["1", "3"], // Pre-fetch these categories
  });

  return (
    <select multiple defaultValue={["1", "3"]}>
      {options.map((option) => (
        <option key={option.value} value={option.value}>
          {option.label}
        </option>
      ))}
    </select>
  );
};

​
With Filters and Sorters

import { useSelect } from "@refinedev/core";

const PostCreate = () => {
  const { options } = useSelect({
    resource: "categories",
    filters: [
      {
        field: "isActive",
        operator: "eq",
        value: true,
      },
    ],
    sorters: [
      {
        field: "name",
        order: "asc",
      },
    ],
  });

  return (
    <select>
      {options.map((option) => (
        <option key={option.value} value={option.value}>
          {option.label}
        </option>
      ))}
    </select>
  );
};

​
Custom Search Implementation

import { useSelect } from "@refinedev/core";

const PostCreate = () => {
  const { options, onSearch } = useSelect({
    resource: "products",
    onSearch: (value) => [
      {
        field: "name",
        operator: "contains",
        value,
      },
      {
        field: "description",
        operator: "contains",
        value,
      },
    ],
  });

  return (
    <div>
      <input
        type="text"
        placeholder="Search by name or description..."
        onChange={(e) => onSearch(e.target.value)}
      />
      
      <select>
        {options.map((option) => (
          <option key={option.value} value={option.value}>
            {option.label}
          </option>
        ))}
      </select>
    </div>
  );
};

Build docs developers (and LLMs) love

Get started for freeTalk to us