# Checkbox

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

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

## Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-checkbox--default.tsx)

```tsx
// 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;
```

## 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).

```ts
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.

[Setup and dependencies](/coreai-design-system/guides/Package.md).

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

Source: Fluent, adapted for CoreAI.

A checkbox can be initially checked using `defaultChecked`, or controlled via the `checked` property.

[Download source](/coreai-design-system/source/examples/components-checkbox--checked.tsx)

```tsx
// 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

Source: Fluent, adapted for CoreAI.

A checkbox can have a circular shape.<br />**Usage warning**: Unless you are designing a tasks experience, we strongly discourage using this styling variant, as it can be confused with `RadioItem`.

[Download source](/coreai-design-system/source/examples/components-checkbox--circular.tsx)

```tsx
// 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

Source: Fluent, adapted for CoreAI.

A checkbox can be disabled.

[Download source](/coreai-design-system/source/examples/components-checkbox--disabled.tsx)

```tsx
// 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

Source: Fluent, adapted for CoreAI.

The label can be placed before the checkbox.

[Download source](/coreai-design-system/source/examples/components-checkbox--label-before.tsx)

```tsx
// 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

Source: Fluent, adapted for CoreAI.

The label will wrap if it is wider than the available space. The checkbox indicator will stay aligned to the first line of text.

[Download source](/coreai-design-system/source/examples/components-checkbox--label-wrapping.tsx)

```tsx
// 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

Source: Fluent, adapted for CoreAI.

A checkbox can be large in size.

[Download source](/coreai-design-system/source/examples/components-checkbox--large.tsx)

```tsx
// 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

Source: Fluent, adapted for CoreAI.

A checkbox can be initially mixed (also known as indeterminate) using `defaultChecked="mixed"`, or controlled via `checked="mixed"`.<br />In this example, the mixed state is used when a group of options has differing values.

[Download source](/coreai-design-system/source/examples/components-checkbox--mixed.tsx)

```tsx
// 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

Source: Fluent, adapted for CoreAI.

When a checkbox is marked as `required`, its label also gets the required styling.

[Download source](/coreai-design-system/source/examples/components-checkbox--required.tsx)

```tsx
// 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;
```

## Resources

- [Figma component](https://www.figma.com/design/eXfSQrRg3poHRgmr0ivN5V/CoreAI-Figma-Library?node-id=116-46830)
- [Fluent guidance](https://fluent2.microsoft.design/components/web/react/core/checkbox/usage)