Skip to main content
RefineDocumentation
Version: 5.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],
});

selectedOptionsOrder​

selectedOptionsOrder allows us to sort selectedOptions on defaultValue. It can be:

  • "in-place": sort selectedOptions at the bottom. It is by default.
  • "selected-first": sort selectedOptions at the top.
const { selectProps } = useCheckboxGroup({
  resource: "languages",
  defaultValue: [1, 2],
  selectedOptionsOrder: "selected-first", // in-place | selected-first
});

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

These properties also support nested property access with Object path syntax.

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

It's also possible to pass function to these props. These functions will receive item argument.

const { options } = useCheckboxGroup({
  optionLabel: (item) => `${item.firstName} ${item.lastName}`,
  optionValue: (item) => item.id,
});

searchField​

Can be used to specify which field will be searched with value given to onSearch function.

const { onSearch } = useCheckboxGroup({ searchField: "name" });

onSearch("John"); // Searches by `name` field with value John.

By default, it uses optionLabel's value, if optionLabel is a string. Uses title field otherwise.

// When `optionLabel` is string.
const { onSearch } = useCheckboxGroup({ optionLabel: "name" });

onSearch("John"); // Searches by `name` field with value John.

// When `optionLabel` is function.
const { onSearch } = useCheckboxGroup({
  optionLabel: (item) => `${item.id} - ${item.name}`,
});

onSearch("John"); // Searches by `title` field with value John.

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 } = useCheckboxGroup({
  resource: "categories",
  pagination: { currentPage: 3, pageSize: 8 },
});

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

API Reference​

Properties​

PropertyTypeDescriptionDefault
resource
﹡

string

Resource name for API data interactions

successNotification

false

OpenNotificationParams

((data?: GetListResponse<TData>, values?: { pagination?: Pagination; sorters?: CrudSort[]

undefined; filters?: CrudFilter[]

undefined; meta?: MetaQuery

undefined; dataProviderName?: string

undefined; }

undefined, resource?: string

undefined) => fal...

Success notification configuration to be displayed when the mutation is successful.

'"There was an error creating resource (status code: statusCode)" or "Error when updating resource (status code: statusCode)"'

errorNotification

false

OpenNotificationParams

((error?: TError, values?: { pagination?: Pagination; sorters?: CrudSort[]

undefined; filters?: CrudFilter[]

undefined; meta?: MetaQuery

undefined; dataProviderName?: string

undefined; }

undefined, resource?: string

undefined) => false

... 1 more...

Error notification configuration to be displayed when the mutation fails.

'"There was an error creating resource (status code: statusCode)" or "Error when updating resource (status code: statusCode)"'

meta

MetaQuery

Additional meta data to pass to the useMany from the data provider

liveMode

"auto" | "manual" | "off"

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.

"off"

liveParams

{ ids?: BaseKey[]; [key: string]: any; }

Params to pass to liveProvider's subscribe method if liveMode is enabled.

undefined

dataProviderName

string

Additional meta data to pass to the useMany from the data provider /** If there is more than one dataProvider, you should use the dataProviderName that you will use.

default

onLiveEvent

(event: LiveEvent) => void

Callback to handle all related live events of this hook.

undefined

queryOptions

MakeOptional<UseQueryOptions<GetListResponse<TQueryFnData>, TError, GetListResponse<TData>, readonly unknown[]>, "queryFn"

"queryKey">

react-query useQuery options

overtimeOptions

UseLoadingOvertimeCoreOptions

onSearch

((value: string) => CrudFilter[])

If defined, this callback allows us to override all filters for every search request.

undefined

pagination

{ currentPage? : number; pageSize?: number;}

Pagination option from useList()

undefined

filters

CrudFilter[]

Resource name for API data interactions

sorters

CrudSort[]

Allow us to sort the options

optionLabel

string

((item: TData) => string)

Set the option's label value

"title"

optionValue

string

((item: TData) => string)

Set the option's value

"id"

searchField

string

If provided optionLabel is a string, uses optionLabel's value.

"title"

selectedOptionsOrder

"in-place" | "selected-first"

Allow us to sort the selection options

in-place

debounce

number

The number of milliseconds to delay

300

defaultValueQueryOptions

MakeOptional<UseQueryOptions<GetManyResponse<TQueryFnData>, TError, GetManyResponse<TData>, readonly unknown[]>, "queryFn"

"queryKey">

react-query useQuery options

defaultValue

BaseKey[]

Sets the default value

Type Parameters​

PropertyDescriptionTypeDefault
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​

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

Previous
useSelect
Next
useRadioGroup