Basic usage

Used for selecting one or multiple items from several options. In cases there is only one Checkbox, it will be used to trigger a specific setting like a switch, the main difference is that the Switch will take effect immediately.

Checkbox can be controlled (checked and onChange required) or uncontrolled. A component should not change from controlled to uncontrolled and vice versa. If a value other than undefined is passed to the checked property, the Checkbox will be rendered as controlled.

Props

Checkbox
System Props

  • COMMON
  • TYPOGRAPHY
  • BORDER
  • LAYOUT
  • POSITION
  • FLEX
  • GRID
  • Learn More
NameTypeDescription
gradientResponsiveValue<TLengthStyledSystem, Required<Theme<TLengthStyledSystem>>>-
checkedbooleanWhether the checkbox is selected or not. If undefined, it becomes an uncontrolled component.
classNamestringThe class attached to the <label> or <span> element that wraps the checkbox.
defaultCheckedbooleanThe default checked value, useful for uncontrolled checkboxes. https://reactjs.org/docs/uncontrolled-components.html#default-values
disabledbooleanMakes checkbox readonly.
indeterminatebooleanIf `true`, the component appears indeterminate. This does not affect the actual checkedness of the checkbox but it will expose the mixed state to assistive technologies.
inputPropsPartial<Pick<Pick<Pick<Pick<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "size" | ... 285 more ... | "onTransitionEndCapture"> & ... 18 more ... & { ...; }, "bottom" | ... 404 more ... | "checkboxSize"> & Partial<...>, "bottom" | ... 405 more ... | "checkboxSize"> & { ...; }, "bottom" ...These props will be passed down into the input checkbox element. `type` prop is not accepted since its hardcoded to "checkbox".
labelTextReactNodeLabel text that describes the checkbox option. If not present, make sure the checkbox is properly labeled.
labelPosition"left" | "right"Label text position relative to the checkbox. By default it's placed on the right.
labelAlignment"top" | "middle"Sets the vertical alignment of the control with multi-line, wrapped labels. By default, it's aligned to middle.
namestringName of the input form control. Submitted with the form as part of a name/value pair.
onChange(event: FormEvent<HTMLInputElement>) => voidEvent handler for the checkbox. You can access its checked state with event.currentTarget.checked
size"medium" | "small"Size variant
valuestringCurrent value of the form control. Submitted with the form as part of a name/value pair.

Accessibility

  • By default, Checkbox will wrap the input with a label. If a different UI is desired, ensure id is provided to Checkbox and properly associate a Label with htmlFor