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 { Form, Checkbox, useCheckboxGroup } from "@pankod/refine";

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: string;
    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. Refer to useList hook for details. →

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.

Refer to Ant Design Checkbox.Group component documentation for detailed info for options. →

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".

filters

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

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

sort

const { checkboxGroupProps } = useCheckboxGroup({
    resource: "tags",
    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.

queryOptions

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

useQuery options can be set by passing queryOptions property.

API Reference

Properties

Property	Description	Type	Default
resource Required	Resource name for API data interactions	string
optionValue	Sets the option's value	string	"id"
optionLabel	Sets the option's label value	string	"title"
filters	Adds filters while fetching the data	CrudFilters
sort	Allows us to sort the options	CrudSorting
queryOptions	react-query useQuery options	UseQueryOptions<GetListResponse<TData>, TError>
metaData	Metadata query for dataProvider	MetaDataQuery	{}
liveMode	Whether 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"
liveParams	Params to pass to liveProvider's subscribe method if liveMode is enabled.	{ ids?: string[]; [key: string]: any; }	undefined
onLiveEvent	Callback to handle all related live events of this hook.	(event: LiveEvent) => void	undefined

Return values

Property	Description	Type
checkboxGroupProps	Ant design checkbox group properties	Checkbox Group
queryResult	Results of the query of a record	QueryObserverResult<{ data: TData }>

Live Codesandbox Example