Checkbox

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

Checkbox

Property	Description	Type	Default	Global 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, string> \| (info: { props })=> Record<SemanticDOM, 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, CSSProperties> \| (info: { props })=> Record<SemanticDOM, 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

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

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?

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

<Form.Item name="fieldA" valuePropName="checked">
  <Checkbox />
</Form.Item>

Shared native 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

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.