Edit this page
[?] Component size, gzipped: 27kb

Checkbox

Checkboxes are used to provide users with multiple options for selection in a series of options.

When used as a toggle they allow the user to make a binary choice usually (but not limited) in the form of a yes/no or on/off suggestion. Toggles are often used in product settings or as filter options. When engaged (on), Base Web toggles are colored and when disengaged (off) they’re grey.

When to use

  • When a collection of options share context.
  • When a user wants to toggle an option on/off.
  • When a user wants to select multiple options.

Examples

Basic usage

Multiple lines

Error state

Indeterminate state

Disabled state

Alignments

Overriding styles

Overriding sub-components

Focus and ref

As a toggle


Stateful (uncontrolled) usage

As with many of our components, there is also an uncontrolled version, StatefulCheckbox, which manages its own state.

Overrides

Additionally, you can fully customize any part of the Checkbox through the overrides prop. The Checkbox consists of multiple subcomponents that are listed bellow and you can override each one of them. To help you identify the names of these subcomponents, you can highlight them through this selector:


Note: You should always use longhand CSS properties. Mixing shorthands and longhands will lead into strange behaviors!

API

Checkbox API

children React$Node

Component or String value for label of checkbox.

React$Node

overrides object = {}

Checkmark { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Label { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Root { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Input { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Toggle { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ToggleInner { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ToggleTrack { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*

checked boolean = false

Check or uncheck the control.

disabled boolean = false

Disable the checkbox from being changed.

required boolean

Marks the checkbox as required.

isError boolean = false

Renders checkbox in errored state.

inputRef object = ()

Used to get a ref to the input element. Useful for programmatically focusing the input

current union required One of
HTMLInputElement,
null

autoFocus boolean = false

Focus the checkbox on initial render.

type string = "checkbox"

Passed to the input element type attribute

name string

Passed to the input element name attribute

value string

Passed to the input element value attribute

isIndeterminate boolean = false

Indicates a 'half' state for the checkmark. In this case, checked is ignored.

labelPlacement union

How to position the label relative to the checkbox itself.

One of
"top",
"right",
"bottom",
"left"

checkmarkType $Keys<typeof STYLE_TYPE> =

Renders UI as checkmark or toggle switch.

$KeysObject.freeze({ default: "default", toggle: "toggle" })

onChange function = () => undefined

Handler for change events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseEnter function = () => undefined

Handler for mouseenter events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseLeave function = () => undefined

Handler for mouseleave events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseDown function = () => undefined

Handler for mousedown events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseUp function = () => undefined

Handler for mouseup events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onFocus function = () => undefined

handler for focus events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onBlur function = () => undefined

handler for blur events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

Stateful Checkbox API

overrides object

Checkmark { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Label { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Root { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Input { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Toggle { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ToggleInner { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ToggleTrack { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*

children React$Node

Component or String value for label of checkbox.

React$Node

initialState object

Defines the components initial state value

checked boolean
isIndeterminate boolean

autoFocus boolean

Focus the checkbox on initial render.

onChange function

Handler for change events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseEnter function

Handler for mouseenter events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseLeave function

Handler for mouseleave events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onFocus function

Handler for focus events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onBlur function

Handler for blur events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

Stateful Checkbox Container API

overrides object

Checkmark { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Label { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Root { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Input { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
Toggle { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ToggleInner { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*
ToggleTrack { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*

children function

Component or String value for label of checkbox.

* => React$Node

initialState object = { checked: false, isIndeterminate: false }

Defines the components initial state value

checked boolean
isIndeterminate boolean

stateReducer function = (type, nextState) => undefined

A state change handler. Used to override default state transitions.

function
string,
checked boolean
isIndeterminate boolean
,
checked boolean
isIndeterminate boolean
,
SyntheticInputEventHTMLInputElement
=>
checked boolean
isIndeterminate boolean

onChange function = () => undefined

Handler for change events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseEnter function = () => undefined

Handler for mouseenter events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onMouseLeave function = () => undefined

Handler for mouseleave events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onFocus function = () => undefined

Handler for focus events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

onBlur function = () => undefined

Handler for blur events on trigger element.

SyntheticInputEventHTMLInputElement => mixed

autoFocus boolean

Focus the checkbox on initial render.

Checkbox exports

You can import this module like so:

import {StatefulCheckbox} from 'baseui/checkbox'

It exports the following components or utility functions:

  • StatefulCheckbox
  • StatefulContainer
  • Checkbox
  • StyledRoot
  • StyledCheckmark
  • StyledLabel
  • StyledInput
  • StyledToggle
  • StyledToggleInner
  • StyledToggleTrack
  • STATE_TYPE
  • STYLE_TYPE