# Checkbox

- Page: https://jiguang132.com/resources/ant-design/docs/checkbox
- Resource: Ant Design (https://jiguang132.com/resources/ant-design.md)
- All guides: https://jiguang132.com/resources/ant-design/docs.md

Collect user's choices.


## When To Use

- Used for selecting multiple values from several options.
- If you use only one checkbox, it is the same as using Switch to toggle between two states. The difference is that Switch will trigger the state change directly, but Checkbox just marks the state as changed and this needs to be submitted.

## Examples


- Basic · `basic`
- Disabled · `disabled`
- Controlled Checkbox · `controller`
- Checkbox Group · `group`
- Check all · `check-all`
- Use with Grid · `layout`
- Custom semantic dom styling · `style-class`





## API

Common props ref：[Common props](#jguang-common-props)

#### Checkbox

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| checked | Specifies whether the checkbox is selected | boolean | false |  | × |
| classNames | Customize class for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  | 6.0.0 |
| defaultChecked | Specifies the initial state: whether or not the checkbox is selected | boolean | false |  | × |
| disabled | If disable checkbox | boolean | false |  | × |
| indeterminate | The indeterminate checked state of checkbox | boolean | false |  | × |
| onChange | The callback function that is triggered when the state changes | (e: CheckboxChangeEvent) => void | - |  | × |
| onBlur | Called when leaving the component | function() | - |  | × |
| onFocus | Called when entering the component | function() | - |  | × |
| styles | Customize inline style for each semantic structure inside the component. Supports object or function. | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - |  | 6.0.0 |

#### Checkbox.Group

| Property | Description | Type | Default | Version |
| --- | --- | --- | --- | --- |
| defaultValue | Default selected value | (string \| number)\[] | \[] |  |
| disabled | If disable all checkboxes | boolean | false |  |
| name | The `name` property of all `input[type="checkbox"]` children | string | - |  |
| options | Specifies options | string\[] \| number\[] \| Option\[] | \[] |  |
| value | Used for setting the currently selected value | (string \| number \| boolean)\[] | \[] |  |
| title | title of the option | `string` | - |  |
| className | className of the option | `string` | - | 5.25.0 |
| style | styles of the option | `React.CSSProperties` | - |  |
| onChange | The callback function that is triggered when the state changes | (checkedValue: T[]) => void | - |  |

##### Option

```typescript
interface Option {
  label: string;
  value: string;
  disabled?: boolean;
}
```

### Methods

#### Checkbox

| Name          | Description                          | Version |
| ------------- | ------------------------------------ | ------- |
| blur()        | Remove focus                         |         |
| focus()       | Get focus                            |         |
| nativeElement | Returns the DOM node of the Checkbox | 5.17.3  |

## Semantic DOM

| Semantic node | Native description | Version |
| --- | --- | --- |
| `root` | Root element with inline-flex layout, baseline alignment, cursor style, reset styles and other basic checkbox container styles | 6.0.0 |
| `icon` | Checkbox icon element with size, direction, background, border, border-radius, transitions, and checked state checkmark styles | 6.0.0 |
| `label` | Label text element with padding and spacing styles relative to the checkbox | 6.0.0 |

Semantic description source: `vendor/components/checkbox/demo/_semantic.tsx`

## Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

Native ComponentToken declares no directly extractable own fields. Shared tokens and inheritance are defined by the declarations below.

Declaration source: `vendor/components/checkbox/style/index.ts`

```ts
import { unit } from '@ant-design/cssinjs';

import { genFocusOutline, resetComponent } from '../../style';

import { genNoMotionRawStyle, genNoMotionStyle } from '../../style/motion';

import type { FullToken, GenerateStyle } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

// biome-ignore lint/suspicious/noEmptyInterface: ComponentToken need to be empty by default
export interface ComponentToken {}

/**
 * @desc Checkbox 组件的 Token
 * @descEN Token for Checkbox component
 */
interface CheckboxToken extends FullToken<'Checkbox'> {
  /**
   * @desc Checkbox 类名
   * @descEN Checkbox class name
   */
  checkboxCls: string;
  /**
   * @desc Checkbox 尺寸
   * @descEN Size of Checkbox
   */
  checkboxSize: number;
}
```

## FAQ

### Why not work in Form.Item? {#faq-form-item-limitations}

Form.Item default bind value to `value` property, but Checkbox value property is `checked`. You can use `valuePropName` to change bind property.

```tsx | pure
<Form.Item name="fieldA" valuePropName="checked">
  <Checkbox />
</Form.Item>
```


## Shared native props {#jguang-common-props}


> Tips: The following generic properties apply to most antd components; those not supported are described separately.

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |


## Install and reproduce an example

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

## Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

- `vendor/components/checkbox/Checkbox.tsx`
- `vendor/components/checkbox/Group.tsx`
- `vendor/components/checkbox/GroupContext.ts`
- `vendor/components/checkbox/index.tsx`
- `vendor/components/checkbox/style/index.ts`

## Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt