Skip to main content
Version: 3.xx.xx

useSelect

useSelect hook allows you to manage an Ant Design Select component when records in a resource needs to be used as select options.

Usage​

We'll demonstrate how to get data at /categories endpoint from https://api.fake-rest.refine.dev REST API.

https://api.fake-rest.refine.dev/categories
{
[
{
id: 1,
title: "E-business",
},
{
id: 2,
title: "Virtual Invoice Avon",
},
{
id: 3,
title: "Unbranded",
},
];
}
pages/posts/create.tsx
import { Form, Select, useSelect } from "@pankod/refine-antd";

export const PostCreate = () => {
const { selectProps } = useSelect<ICategory>({
resource: "categories",
});

return (
<Form>
<Form.Item label="Categories" name="categories">
<Select {...selectProps} />
</Form.Item>
</Form>
);
};

interface ICategory {
id: number;
title: string;
}
Basic use of select box

All we have to do is pass the selectProps it returns to the <Select> component.

Search functionality

attention

By default, refine does the search using the useList hook and passes it to the search parameter. If you get a problem you should check your getList function in your Data Provider. If you want to change this behavior to make client-side filtering, you can examine this example.

useSelect uses the useList hook for fetching data. Refer to useList hook for details. β†’

Options​

resource​

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

resource property determines API resource endpoint to fetch records from dataProvider. It returns properly configured options values for select options.

Refer to Ant Design Select component documentation for detailed info for options. β†’

defaultValue​

const { selectProps } = useSelect({
resource: "categories",
defaultValue: "1",
});

Adds extra options to <Select> component. It uses useMany so defaultValue can be an array of strings like follows.

defaultValue: ["1", "2"],

Refer to the useMany documentation for detailed usage. β†’

tip

Can use defaultValue property when edit a record in <Edit> component.

optionLabel and optionValue​

const { selectProps } = useSelect({
resource: "categories",
optionLabel: "title",
optionValue: "id",
});

Allows you to change the values and appearance of your options. Default values are optionLabel = "title" and optionValue = "id".

tip

Supports use with optionLabel and optionValue Object path syntax.

const { options } = useSelect({
resource: "categories",
optionLabel: "nested.title",
optionValue: "nested.id",
});

filters​

const { selectProps } = useSelect({
resource: "categories",
filters: [
{
field: "isActive",
operator: "eq",
value: true,
},
],
});

It allows us to add some filters while fetching the data. For example, if you want to list only the active records.

sort​

const { selectProps } = useSelect({
resource: "categories",
sort: [
{
field: "title",
order: "asc",
},
],
});

It allows us to sort the options. For example, if you want to sort your list according to title by ascending.

fetchSize​

const { selectProps } = useSelect({
resource: "categories",
fetchSize: 20,
});

Amount of records to fetch in select box.

onSearch​

const { selectProps } = useSelect({
resource: "categories",
onSearch: (value) => [
{
field: "title",
operator: "containss",
value,
},
],
});

If defined, it allows us to override the filters to use when fetching list of records. Thus, it . It should return CrudFilters.

Client-side filtering​

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

<Select
{...selectProps}
onSearch={undefined}
filterOption={true}
optionFilterProp="label" // or "value"
/>

queryOptions​

const { selectProps } = useSelect({
resource: "categories",
queryOptions: {
onError: () => {
console.log("triggers when on query return Error");
},
},
});

useQuery options can be set by passing queryOptions property.

defaultValueQueryOptions​

When the defaultValue property is given, the useMany data hook is called for the selected records. With this property, you can change the options of this query. If not given, the values given in queryOptions will be used.

const { selectProps } = useSelect({
resource: "categories",
defaultValueQueryOptions: {
onSuccess: (data) => {
console.log("triggers when on query return on success");
},
},
});

useQuery options for default value query can be set by passing queryOptions property.

API Reference​

Properties​

PropertyDescriptionTypeDefault
resource
Required
Resource name for API data interactionsstring
defaultValueAdds extra optionsstring | Array<string>
optionValueSet the option's valuestring"id"
optionLabelSet the option's label valuestring"title"
filtersAdd filters while fetching the dataCrudFilters
sortAllow us to sort the optionsCrudSorting
debounceThe number of milliseconds to delaynumber300
queryOptionsreact-query useQuery options UseQueryOptions<GetListResponse<TData>, TError>
defaultValueQueryOptionsreact-query useQuery options UseQueryOptions<GetManyResponse<TData>, TError>
fetchSizeAmount of records to fetch in select box list.numberundefined
onSearchIf defined, this callback allows us to override all filters for every search request.(value: string) => CrudFilters | Promise<CrudFilters>undefined
metaDataMetadata query for dataProviderMetaDataQuery{}
liveModeWhether to update data automatically ("auto") or not ("manual") if a related live event is received. The "off" value is used to avoid creating a subscription."auto" | "manual" | "off""off"
liveParamsParams to pass to liveProvider's subscribe method if liveMode is enabled.{ ids?: string[]; [key: string]: any; }undefined
onLiveEventCallback to handle all related live events of this hook.(event: LiveEvent) => voidundefined

Return values​

PropertyDescriptionType
selectPropsAnt design Select propsSelect
queryResultResult of the query of a recordQueryObserverResult<{ data: TData }>
defaultValueQueryResultResult of the query of a defaultValue recordQueryObserverResult<{ data: TData }>
defaultValueQueryOnSuccessDefault value onSuccess method() => void

Live StackBlitz Example​