| 1 | ---
|
| 2 | title: Checkbox
|
| 3 | storybookPath: forms-checkbox--default
|
| 4 | isExperimentalPackage: false
|
| 5 | ---
|
| 6 |
|
| 7 | Checkboxes are used to toggle between checked and unchecked states — usually in
|
| 8 | a form. If only one option from a list is allowed to be enable, consider using a
|
| 9 | `RadioButton` instead.
|
| 10 |
|
| 11 | ## Examples
|
| 12 |
|
| 13 | ### Controlled
|
| 14 |
|
| 15 | Checkboxes can be both controlled and uncontrolled. To control a checkbox
|
| 16 | provide the `checked` state with a value you control, as well as an `onChange`
|
| 17 | function to set the new value when the checkbox is toggled.
|
| 18 |
|
| 19 | ```jsx live
|
| 20 | const [checked, setChecked] = React.useState(false);
|
| 21 |
|
| 22 | return (
|
| 23 | <Stack gap="large">
|
| 24 | <Checkbox
|
| 25 | checked={checked}
|
| 26 | onChange={event => setChecked(event.target.checked)}
|
| 27 | >
|
| 28 | <Text>{checked ? 'Hide' : 'Show'} message</Text>
|
| 29 | </Checkbox>
|
| 30 | {checked && <Text>Toggle the checkbox to hide this message</Text>}
|
| 31 | </Stack>
|
| 32 | );
|
| 33 | ```
|
| 34 |
|
| 35 | ### Size
|
| 36 |
|
| 37 | Checkboxes are available in two sizes: `small` and `medium`.
|
| 38 |
|
| 39 | ```jsx live
|
| 40 | <Stack gap="large">
|
| 41 | <Fieldset legend="Checkbox variations (small)" gap="large">
|
| 42 | <Checkbox size="small" checked={false}>
|
| 43 | Unchecked
|
| 44 | </Checkbox>
|
| 45 | <Checkbox size="small" checked>
|
| 46 | Checked
|
| 47 | </Checkbox>
|
| 48 | <Checkbox size="small" disabled>
|
| 49 | Disabled
|
| 50 | </Checkbox>
|
| 51 | <Checkbox size="small" checked disabled>
|
| 52 | Checked + disabled
|
| 53 | </Checkbox>
|
| 54 | </Fieldset>
|
| 55 | <Divider />
|
| 56 | <Fieldset legend="Checkbox variations (medium)" gap="large">
|
| 57 | <Checkbox size="medium" checked={false}>
|
| 58 | Unchecked
|
| 59 | </Checkbox>
|
| 60 | <Checkbox size="medium" checked>
|
| 61 | Checked
|
| 62 | </Checkbox>
|
| 63 | <Checkbox size="medium" disabled>
|
| 64 | Disabled
|
| 65 | </Checkbox>
|
| 66 | <Checkbox size="medium" checked disabled>
|
| 67 | Checked + disabled
|
| 68 | </Checkbox>
|
| 69 | </Fieldset>
|
| 70 | </Stack>
|
| 71 | ```
|
| 72 |
|
| 73 | ### Message and tone
|
| 74 |
|
| 75 | The `message` is used to communicate the status of a field, such as an error
|
| 76 | message. This will be announced on focus and can be combined with a `tone` to
|
| 77 | illustrate intent. The supported tones are: `critical`, `positive` and
|
| 78 | `neutral`.
|
| 79 |
|
| 80 | ```jsx live
|
| 81 | <Fieldset legend="Message and tone" gap="large">
|
| 82 | <Checkbox message="Critical message" tone="critical">
|
| 83 | Critical
|
| 84 | </Checkbox>
|
| 85 | <Checkbox message="Positive message" tone="positive">
|
| 86 | Positive
|
| 87 | </Checkbox>
|
| 88 | <Checkbox message="Neutral message" tone="neutral">
|
| 89 | Neutral
|
| 90 | </Checkbox>
|
| 91 | </Fieldset>
|
| 92 | ```
|
| 93 |
|
| 94 | ## Props
|
| 95 |
|
| 96 | ### Checkbox
|
| 97 |
|
| 98 | <PropsTable displayName="Checkbox" />
|
| 99 |
|
| 100 | The `Checkbox` component also extends `InputHTMLAttributes` props and are not
|
| 101 | listed here.
|
| 102 |
|
| 103 | ### CheckboxPrimitive
|
| 104 |
|
| 105 | <PropsTable displayName="CheckboxPrimitive" />
|
| 106 |
|
| 107 | The `CheckboxPrimitive` component also extends `InputHTMLAttributes` props and
|
| 108 | are not listed here.
|
| 109 |
|
| 110 | [data-attribute-map]:
|
| 111 | https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1
|