Skip to main content
🧙‍♂️ refine grants your wishes! Please give us a ⭐️ on GitHub to keep the magic going.
Version: 4.xx.xx

useCheckboxGroup

useCheckboxGroup hook allows you to manage an Ant Design Checkbox.Group component when records in a resource needs to be used as checkbox options.

Usage

We will demonstrate how to get data at the /tags endpoint from the https://api.fake-rest.refine.dev REST API.

https://api.fake-rest.refine.dev/tags
{
[
{
id: 1,
title: "Driver Deposit",
},
{
id: 2,
title: "Index Compatible Synergistic",
},
{
id: 3,
title: "Plum",
},
];
}
pages/posts/create.tsx
import { useCheckboxGroup } from "@refinedev/antd";
import { Form, Checkbox } from "antd";

export const PostCreate: React.FC = () => {
const { checkboxGroupProps } = useCheckboxGroup<ITag>({
resource: "tags",
});

return (
<Form>
<Form.Item label="Tags" name="tags">
<Checkbox.Group {...checkboxGroupProps} />
</Form.Item>
</Form>
);
};

interface ITag {
id: number;
title: string;
}

All we have to do is pass the checkboxGroupProps it returns to the <Checkbox.Group> component. useCheckboxGroup uses the useList hook for fetching data.

Tags

For more information, refer to the useList documentation

Options

resource

const { checkboxGroupProps } = useCheckboxGroup({
resource: "tags",
});

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

If you have multiple resources with the same name, you can pass the identifier instead of the name of the resource. It will only be used as the main matching key for the resource, data provider methods will still work with the name of the resource defined in the <Refine/> component.

For more information, refer to the identifier section of the <Refine/> component documentation

For more information, refer to the Ant Design's Checkbox.Group component documentation

defaultValue

const { selectProps } = useCheckboxGroup({
resource: "languages",
defaultValue: [1, 2],
});

The easiest way to select default values for checkbox fields is by passing in defaultValue.

optionLabel and optionValue

const { checkboxGroupProps } = useCheckboxGroup({
resource: "tags",
optionLabel: "title",
optionValue: "id",
});

optionLabel and optionValue allows you to change the values and appearances 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

filters allows us to add filters while fetching the data. For example, if you want to list only the titles that are equal to "Driver Deposit":

const { checkboxGroupProps } = useCheckboxGroup({
resource: "tags",
filters: [
{
field: "title",
operator: "eq",
value: "Driver Deposit",
},
],
});

sorters

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

const { checkboxGroupProps } = useCheckboxGroup({
resource: "tags",
sorters: [
{
field: "title",
order: "asc",
},
],
});

fetchSize

fetchSize is the amount of records to fetch in checkboxes.

const { selectProps } = useCheckboxGroup({
resource: "languages",
fetchSize: 20,
});

queryOptions

Passing the queryOptions property allows us to set the useQuery options

const { checkboxGroupProps } = useCheckboxGroup({
resource: "tags",
queryOptions: {
onError: () => {
console.log("triggers when on query return Error");
},
},
});

pagination

pagination allows us to set page and items per page values.

For example, lets say that we have 1000 post records:

const { selectProps } = useSelect({
resource: "categories",
pagination: { current: 3, pageSize: 8 },
});

The listing will start from page 3, showing 8 records per page.

sort

Deprecated

Use sorters instead.

API Reference

Properties

Type Parameters

PropertyDesriptionTypeDefault
TQueryFnDataResult data returned by the query function. Extends BaseRecordBaseRecordBaseRecord
TErrorCustom error object that extends HttpErrorHttpErrorHttpError
TDataResult data returned by the select function. Extends BaseRecord. If not specified, the value of TQueryFnData will be used as the default value.BaseRecordTQueryFnData

Example

Run on your local
npm create refine-app@latest -- --example field-antd-use-checkbox-group