Checkbox
View .mdCheckboxes let people select multiple options from a group or switch a single option on or off. To restrict someone to picking one option, try a radio group or dropdown.
Default
Loading interactive example. Full source is available below.
View example source
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { CheckboxProps } from "@coreai-ds/react-components";
import type { JSXElement } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
import * as React from 'react';
export const Default = (props: CheckboxProps): JSXElement => <Checkbox {...props}/>;
export default Default;
Resources
Best practices
Do
- Use checkboxes to allow users to select any number of options, including zero, one, or several.
- Use a radio group if only one option can be selected from a group.
- Use a multiselect if the group of non-mutually exclusive options is higher than seven.
- Use checkboxes for options that turn a group of elements on or off.
- When providing a default selection state, consider the recommended or most likely choice for a user.
Don't
- Use checkboxes for options that require descriptions to understand the implications of both the on and off states. Use a radio group instead.
- Use checkboxes for options that take immediate effect. Use a toggle instead.
- Label a checkbox as optional.
Behavior and states
- If one checkbox controls a subset of options, selecting or clearing the parent checkbox selects or clears all of the children.
- Use an indeterminate state to show when some, but not all, of the options are selected.
- Create a visual separation between parent and child checkboxes to increase scannability.
- Checkboxes don’t trigger an immediate change and require a submission step, like selecting a button.
- If you need a component that has immediate effect, try a switch.
API referenceGenerated CoreAI prop and type summaries
API
Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. ? means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.
Checkbox API
Checkboxes give people a way to select one or more items from a group, or switch between two mutually exclusive options (checked or unchecked).
interface CheckboxProps {
as?: "input";
/**
* The controlled value for the checkbox.
* @default false
*/
checked?: boolean | "mixed";
/**
* Checkboxes don't support children. To add a label, use the `label` prop.
*/
children?: undefined;
className?: string;
/**
* Whether the checkbox should be rendered as checked by default.
*/
defaultChecked?: boolean | "mixed";
/**
* The checkbox, with the checkmark icon as its child when checked.
*/
indicator?: WithSlotShorthandValue<{ as?: "div"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & { ref?: ((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null; }, "children"> & { children?: any; }> | ({ as: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null | undefined; }, "children"> & { children?: any; }) | null | undefined;
/**
* Hidden input that handles the checkbox's functionality.
*
* This is the PRIMARY slot: all native properties specified directly on `<Checkbox>` will be applied to this slot,
* except `className` and `style`, which remain on the root slot.
*/
input?: ({ as?: "input"; } & Omit<Omit<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & { ref?: ((instance: HTMLInputElement | null) => void) | RefObject<HTMLInputElement> | null; }, "children"> & { children?: undefined; }) | undefined;
/**
* The Checkbox's label.
*/
label?: WithSlotShorthandValue<Omit<ComponentProps<LabelSlots>, "required"> & { disabled?: boolean; required?: boolean | WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null | undefined; }, "children"> & { children?: any; }> | null | undefined; size?: "small" | "medium" | "large" | undefined; weight?: "regular" | "semibold" | undefined; } & RefAttributes<HTMLLabelElement>> | null | undefined;
/**
* The position of the label relative to the checkbox indicator.
* @default after
*/
labelPosition?: "before" | "after";
/**
* Callback to be called when the checked state value changes.
*/
onChange?: ((ev: ChangeEvent<HTMLInputElement>, data: CheckboxOnChangeData) => void);
ref?: Ref<HTMLInputElement>;
/**
* The root element of the Checkbox.
*
* The root slot receives the `className` and `style` specified directly on the `<Checkbox>`.
* All other native props will be applied to the primary slot: `input`
*/
root?: NonNullable<WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null> | undefined;
/**
* The shape of the checkbox indicator.
*
* The `circular` variant is only recommended to be used in a tasks-style UI (checklist),
* since it otherwise could be confused for a `RadioItem`.
* @default square
*/
shape?: "circular" | "square";
/**
* The size of the checkbox indicator.
* @default medium
*/
size?: "medium" | "large";
style?: CSSProperties;
}
Implementation
CoreAI 0.12.0; Fluent 9.74.9.
Import components from @coreai-ds/react-components. CoreAI guidance above takes precedence over API demonstration examples.
Note: Storybook-only layout decorators are omitted. Examples use the documentation preview spacing instead.
Checked
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import * as React from 'react';
import type { CheckboxProps } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
export const Checked = (): JSXElement => {
const [checked, setChecked] = React.useState<CheckboxProps['checked']>(true);
return <Checkbox checked={checked} onChange={(ev, data) => setChecked(data.checked)} label="Checked"/>;
};
export default Checked;
Circular
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
import * as React from 'react';
export const Circular = (): JSXElement => <Checkbox shape="circular" label="Circular"/>;
export default Circular;
Disabled
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
import * as React from 'react';
export const Disabled = (): JSXElement => (<>
<Checkbox disabled label="Disabled"/>
<Checkbox disabled label="Disabled checked" checked/>
<Checkbox disabled label="Disabled mixed" checked="mixed"/>
</>);
export default Disabled;
Label Before
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
import * as React from 'react';
export const LabelBefore = (): JSXElement => <Checkbox labelPosition="before" label="Label before"/>;
export default LabelBefore;
Label Wrapping
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
import * as React from 'react';
export const LabelWrapping = (): JSXElement => (<Checkbox style={{ maxWidth: '400px' }} label="Here is an example of a checkbox with a long label and it starts to wrap to a second line"/>);
export default LabelWrapping;
Large
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
import * as React from 'react';
export const Large = (): JSXElement => <Checkbox size="large" label="Large"/>;
export default Large;
Mixed
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import * as React from 'react';
import { Checkbox } from "@coreai-ds/react-components";
export const Mixed = (): JSXElement => {
const [option1, setOption1] = React.useState(false);
const [option2, setOption2] = React.useState(true);
const [option3, setOption3] = React.useState(false);
return (<>
<Checkbox checked={option1 && option2 && option3 ? true : !(option1 || option2 || option3) ? false : 'mixed'} onChange={(_ev, data) => {
setOption1(!!data.checked);
setOption2(!!data.checked);
setOption3(!!data.checked);
}} label="All options"/>
<Checkbox checked={option1} onChange={() => setOption1(checked => !checked)} label="Option 1"/>
<Checkbox checked={option2} onChange={() => setOption2(checked => !checked)} label="Option 2"/>
<Checkbox checked={option3} onChange={() => setOption3(checked => !checked)} label="Option 3"/>
</>);
};
export default Mixed;
Required
Loading interactive example. Full source is available below.
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.
import type { JSXElement } from "@coreai-ds/react-components";
import { Checkbox } from "@coreai-ds/react-components";
import * as React from 'react';
export const Required = (): JSXElement => <Checkbox required label="Required"/>;
export default Required;