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

Checkbox basic usage

Checkbox uncontrolled usage

Checkbox multiline example

Checkbox with error

Checkbox indeterminate state

Checkbox disabled example

Checkbox alignment example

Checkbox with overrides

Checkbox with component overrides

Checkbox focus with button

Checkbox as a toggle


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!

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.