@workday/canvas-kit-docs/dist/mdx/react/checkbox/Checkbox.mdx

Documentation components of Canvas Kit components

import {
  ExampleCodeBlock,
  SymbolDoc,
  Specifications,
  InformationHighlight,
} from '@workday/canvas-kit-docs';
import Caution from './examples/Caution';
import Basic from './examples/Basic';
import Inverse from './examples/Inverse';
import Disabled from './examples/Disabled';
import Error from './examples/Error';
import Indeterminate from './examples/Indeterminate';
import LabelPosition from './examples/LabelPosition';
import RefForwarding from './examples/RefForwarding';
import Required from './examples/Required';


# Canvas Kit Checkbox

Checkboxes allow a user to select zero, one, or multiple values from a predefined list of 7 or less
options.

[> Workday Design Reference](https://design.workday.com/components/inputs/checkboxes)

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

### Basic Example

Checkbox may be used on its own without [Form Field](/components/inputs/form-field/) since it
includes a `<label>` with a `for` attribute referencing the underlying `<input type="checkbox">`
element.

<ExampleCodeBlock code={Basic} />

### Inverse

Checkbox with inverse variation

<ExampleCodeBlock code={Inverse} />

### Disabled

Set the `disabled` prop of the Checkbox to prevent users from interacting with it.

<ExampleCodeBlock code={Disabled} />

### Indeterminate

Set the `indeterminate` prop of the Checkbox to `true` to indicate the Checkbox is neither checked
nor unchecked.

A common use case for an indeterminate Checkbox is when the value of a parent Checkbox is dependent
on a number of child Checkboxes. The parent Checkbox is set to the indeterminate state if some (but
not all) of its children are checked.

<ExampleCodeBlock code={Indeterminate} />

### Ref Forwarding

Checkbox supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
`ref` to its underlying `<input type="checkbox">` element.

<ExampleCodeBlock code={RefForwarding} />

### Label Position Horizontal

Set the `orientation` prop of the Form Field to designate the position of the label relative to the
input component. By default, the orientation will be set to `vertical`.

<ExampleCodeBlock code={LabelPosition} />

### Required

Set the `required` prop of a wrapping Form Field to `true` to indicate that the field is required.
Labels for required fields are suffixed by a red asterisk.

<ExampleCodeBlock code={Required} />

### Error States

Set the `error` prop of the wrapping Form Field to `"caution"` or
`"error"` to set the Checkbox to the Alert or Error state, respectively. You will
also need to set the `hintId` and `hintText` props on the Form Field to meet accessibility
standards. You may wish to omit the `label` prop on the Form Field given that Checkbox already
includes a label.

The `error` prop may be applied directly to the Checkbox with a value of `"caution"`
or `"error"` if Form Field is not being used.

#### Caution

<ExampleCodeBlock code={Caution} />

#### Error

<ExampleCodeBlock code={Error} />

### Custom Styles

Checkbox supports custom styling via the `cs` prop. For more information, check our
["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs).

## Component API

<SymbolDoc name="Checkbox" fileName="/react/" />

## Specifications

<Specifications file="Checkbox.spec.ts" name="Checkbox" />