CheckBox

The CheckBox component is used in forms when a user needs to select multiple values from several options.

Import#

Pearl UI exports 2 checkbox-related components:

CheckBox: A single checkbox which can be checked and unchecked.
CheckBoxGroup: A wrapper which stacks multiple CheckBox components together and provides a central place to control their state.

import { CheckBox, CheckBoxGroup } from "pearl-ui";

Usage#

const [checked, setIsChecked] = React.useState(false)
<CheckBox isChecked={checked} onPress={() => setIsChecked(!checked)}>Check Me!</CheckBox>

Checkbox group#

A CheckboxGroup component exists to help manage the checked state of its children CheckBox components and conveniently pass a few shared style props to each as follows:

const [checkedGroupValue, setCheckedGroupValue] = React.useState([])
<CheckBoxGroup  size="s"  colorScheme="secondary"  shape="circle"  defaultValue={["1", "2"]}  value={checkedGroupValue}  onChange={(value) => {    setCheckedGroupValue(value);  }}>  <Stack direction="vertical" spacing="xs">    <CheckBox value="1">Value 1</CheckBox>    <CheckBox value="2">Value 2</CheckBox>    <CheckBox value="3">Value 3</CheckBox>    <CheckBox value="4">Value 4</CheckBox>  </Stack></CheckBoxGroup>

Checkbox sizes#

Use the size prop to change the size of the checkbox. You can set the value to the keys available in PearlTheme.components.CheckBox["sizes"], which are "s", "m", "l", and "xl" in the default theme.

<CheckBox size="s">Small Checkbox</CheckBox>
<CheckBox size="m">Regular Checkbox</CheckBox>
<CheckBox size="l">Large Checkbox</CheckBox>
<CheckBox size="xl">Extra Large Checkbox</CheckBox>

Checkbox variants#

Use the variant prop to change the visual style of the checkbox. You can set the value to the keys available in PearlTheme.components.CheckBox["variants"], which are "filled" and "outline" in the default theme.

<CheckBox variant="filled">Filled Checkbox</CheckBox>
<CheckBox variant="outline">Outline Checkbox</CheckBox>

Checkbox color scheme#

Use the colorScheme prop to change the color palette of the checkbox. This is much more powerful than simply passing a backgroundColor style prop as the colorScheme prop changes all the use color values in a palette through a single prop.

You can set the value only to the keys available in PearlTheme.palette that contain a palette of colors represented as an object, which are "primary", "secondary", "neutral", etc in the default Pearl theme.

<CheckBox colorScheme="primary">Primary Checkbox</CheckBox>
<CheckBox colorScheme="secondary">Secondary Checkbox</CheckBox>

Checkbox shape#

You can use the shape prop to change the shape of the checkbox to "square" or "circle". By default, this value equals to "square".

<CheckBox shape="square">Square Checkbox</CheckBox>
<CheckBox shape="circle">Circle Checkbox</CheckBox>

Checkbox checked state#

The checkbox is in a checked state when it is pressed once and the checkmark icon becomes visible. The isChecked prop is used to define whether the checkbox is in a checked state.

Checkbox also allows you to update the visual style of the checkbox when it is checked using some special props prefixed with the word checked.

<CheckBox isChecked checkedBackgroundColor="cyan" checkedBorderColor="violet">  I am checked!</CheckBox>

Checkbox indeterminate state#

In some special scenarios, you might need to display a partial checked state(also called an Indeterminate state) by displaying an alternate icon to the user. The isIndeterminate prop is used to define whether the checkbox is in an indeterminate state.

<CheckBox  isChecked  isIndeterminate  checkedBackgroundColor="cyan"  checkedBorderColor="violet">  I am not completely checked!</CheckBox>

Checkbox error state#

Similar to the checked state, you can add an error state to the checkbox based on any validation criteria you use along with special visual styles to go along with it by using some special props prefixed with the word error. The isInvalid prop is used to define whether the checkbox has an error.

You can also pass the errorMessage prop to add a helper text describing the error below the checkbox.

<CheckBox  isInvalid  errorBackgroundColor="pink"  errorBorderColor="red">  Error Checkbox</CheckBox>
<CheckBox  isInvalid  errorBackgroundColor="cyan"  errorBorderColor="violet"  errorMessage="This is an error message!">  Error Checkbox with message</CheckBox>

Changing the spacing#

You can use the spacing prop to customize the spacing between the checkbox and label text. You can set the value to the keys available in PearlTheme.spacing, which are "xs", "s", "l", etc. in the default Pearl theme. By default, this value equals to "xs".

<CheckBox spacing="l">Checkbox with lots of spacing</CheckBox>
<CheckBox spacing="xs">Checkbox with less spacing</CheckBox>

Changing the icons#

You can also customize the icons to be used in the checkbox using the following props:

checkedIconFamily
checkedIconName
indeterminateIconFamily
indeterminateIconName

<CheckBox  isChecked  checkedIconFamily="AntDesign"  checkedIconName="plus"  indeterminateIconFamily="MaterialCommunityIcons"  indeterminateIconName="music-note-half">  Custom Checkbox</CheckBox>

Override Style#

The CheckBox component also supports a variety of style props which can be used to override the pre-defined variant style in the theme. Manual style props passed into the component have a higher precedance than the default component style.

// passing style prop marginTop="l" adds a top margin to the checkbox<CheckBox variant="filled" marginTop="l" borderWidth={2} borderColor="green">  Check Me!</CheckBox>

Example#

Light
Dark

Embed not loading? Click here

Accessibility#

CheckBox has the role of checkbox.
When the CheckBox is disabled or checked, it is reflected as disabled and checked respectively in screen readers.
CheckBox has the default accessibility label set as the label text passed into it. A custom label can be specified using the accessibilityLabel prop.

CheckBox Props#

Supported style props#

CheckBox composes the Stack component, you can pass all Stack props to CheckBox.

Additional props#

Name	Required	Type	Default	Description
size	false	PearlTheme.components.CheckBox["sizes"]	`"m"`	Size of the checkbox.
variant	false	PearlTheme.components.CheckBox["variants"]	`"filled"`	Variant of the checkbox.
value	false	string \| number \| undefined		Value of the checkbox if it is part of a group.
isDisabled	false	boolean	`false`	Whether the checkbox is disabled.
isChecked	false	boolean	`false`	Whether the checkbox is in a checked state.
isIndeterminate	false	boolean	`false`	Whether the checkbox is in an indeterminate state.
isInvalid	false	boolean	`false`	Whether the checkbox is in an error state.
errorMessage	false	string		The error message to be displayed if the checkbox is in an error state.
colorScheme	false	PearlTheme.palette	`"primary"`	Active color palette of the checkbox.
spacing	false	PearlTheme.spacing	`"xs"`	The spacing between the checkbox and the label text.
shape	false	"square" \| "circle"	`"square"`	Shape of the checkbox.
checkedIconFamily	false	"AntDesign" \| "Entypo" \| "EvilIcons" \| "Feather" \| "FontAwesome" \| "FontAwesome5" \| "Fontisto" \| "Foundation" \| "Ionicons" \| "MaterialCommunityIcons" \| "MaterialIcons" \| "Octicons" \| "SimpleLineIcons" \| "Zocial"	`"Ionicons"`	Family of the icon when the checkbox is in checked state.
checkedIconName	false	string	`"checkmark"`	Name of the icon when the checkbox is in checked state.
indeterminateIconFamily	false	"AntDesign" \| "Entypo" \| "EvilIcons" \| "Feather" \| "FontAwesome" \| "FontAwesome5" \| "Fontisto" \| "Foundation" \| "Ionicons" \| "MaterialCommunityIcons" \| "MaterialIcons" \| "Octicons" \| "SimpleLineIcons" \| "Zocial"	`"Ionicons"`	Family of the icon when the checkbox is in indeterminate state.
indeterminateIconName	false	string	`"remove-outline"`	Name of the icon when the checkbox is in indeterminate state.
checkedBackgroundColor	false	PearlTheme.palette \| ColorModeColor	`"primary.500"`	The background color of the checkbox when it is in checked state.
checkedBorderColor	false	PearlTheme.palette \| ColorModeColor	`"primary.500"`	The border color of the checkbox when it is in checked state
checkedBorderStartColor	false	PearlTheme.palette \| ColorModeColor		The border start color of the checkbox when it is in checked state.
checkedBorderEndColor	false	PearlTheme.palette \| ColorModeColor		The border end color of the checkbox when it is in checked state.
checkedBorderTopColor	false	PearlTheme.palette \| ColorModeColor		The border top color of the checkbox when it is in checked state.
checkedBorderLeftColor	false	PearlTheme.palette \| ColorModeColor		The border left color of the checkbox when it is in checked state.
checkedBorderRightColor	false	PearlTheme.palette \| ColorModeColor		The border right color of the checkbox when it is in checked state.
checkedBorderBottomColor	false	PearlTheme.palette \| ColorModeColor		The border bottom color of the checkbox when it is in checked state.
errorBackgroundColor	false	PearlTheme.palette \| ColorModeColor		The background color of the checkbox when it is in an error state.
errorBorderColor	false	PearlTheme.palette \| ColorModeColor	`"danger.500"`	The border color of the checkbox when it is in an error state
errorBorderStartColor	false	PearlTheme.palette \| ColorModeColor		The border start color of the checkbox when it is in an error state.
errorBorderEndColor	false	PearlTheme.palette \| ColorModeColor		The border end color of the checkbox when it is in an error state.
errorBorderTopColor	false	PearlTheme.palette \| ColorModeColor		The border top color of the checkbox when it is in an error state.
errorBorderLeftColor	false	PearlTheme.palette \| ColorModeColor		The border left color of the checkbox when it is in an error state.
errorBorderRightColor	false	PearlTheme.palette \| ColorModeColor		The border right color of the checkbox when it is in an error state.
errorBorderBottomColor	false	PearlTheme.palette \| ColorModeColor		The border bottom color of the checkbox when it is in an error state.

CheckBoxGroup Props#

Supported style props#

CheckBoxGroup composes the Box component, you can pass all Box props to CheckBoxGroup.

Additional props#

Name	Required	Type	Default	Description
size	false	PearlTheme.components.CheckBox["sizes"]	`"m"`	Size of all the children checkbox in the group.
variant	false	PearlTheme.components.CheckBox["variants"]	`"filled"`	Variant of all the children checkbox in the group.
value	false	Array<string \| number>		Active value of the checkbox group.
defaultValue	false	Array<string \| number>	`[]`	Default active value of the checkbox group.
onChange	false	(value: Array<string \| number>) => void		Method that gets invoked when the value of the checkbox group changes.
isDisabled	false	boolean	`false`	Whether the checkbox group is disabled.
colorScheme	false	PearlTheme.palette	`"primary"`	Active color palette of all the children checkbox in the group.
shape	false	"square" \| "circle"	`"square"`	Shape of all the children checkbox in the group.

Default component Style#

export default {  parts: ["root", "box", "icon", "text", "errorText"],  baseStyle: {    root: {      my: "xxs",      spacing: "xs",    },    box: {      p: "hairline",      shape: "square",      borderColor: "neutral.300",      checkedBackgroundColor: "primary.500",      errorBorderColor: "danger.500",    },    icon: {      checkedIconFamily: "Ionicons",      checkedIconName: "checkmark",      indeterminateIconFamily: "Ionicons",      indeterminateIconName: "remove-outline",      color: "neutral.50",    },    errorText: {      variant: "caption",      color: "danger.500",      marginBottom: "xxs",    },  },  sizes: {    s: {      box: {        borderRadius: "s",      },      icon: {        size: "s",      },      text: {        variant: "p2",      },    },    m: {      box: {        borderRadius: "s",      },      icon: {        size: "m",      },      text: {        variant: "p2",      },    },    l: {      box: {        borderRadius: "m",      },      icon: {        size: "l",      },      text: {        variant: "p1",      },    },    xl: {      box: {        borderRadius: "m",      },      icon: {        size: "xl",      },      text: {        variant: "p1",      },    },  },  variants: {    filled: {      box: {        borderWidth: 2,        backgroundColor: {          light: "neutral.200",          dark: "neutral.900",        },        borderColor: {          light: "neutral.200",          dark: "neutral.600",        },        checkedBorderColor: "primary.500",      },    },    outline: {      box: {        borderWidth: 2,        backgroundColor: {          light: "neutral.50",          dark: "neutral.800",        },        borderColor: {          light: "neutral.400",          dark: "neutral.500",        },        checkedBorderColor: "primary.500",      },    },  },  defaults: {    size: "m",    variant: "filled",  },};