Skip to main content

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:

  1. CheckBox: A single checkbox which can be checked and unchecked.
  2. 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 config.

// 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#

Accessibility#

  • CheckBox has the role of checkbox.
  • When 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 it.

Additional props#

NameRequiredTypeDefaultDescription
sizefalsePearlTheme.components.CheckBox["sizes"]"m"Size of the checkbox.
variantfalsePearlTheme.components.CheckBox["variants"]"filled"Variant of the checkbox.
valuefalsestring | number | undefinedValue of the checkbox if it is part of a group.
isDisabledfalsebooleanfalseWhether the checkbox is disabled.
isCheckedfalsebooleanfalseWhether the checkbox is in a checked state.
isIndeterminatefalsebooleanfalseWhether the checkbox is in an indeterminate state.
isInvalidfalsebooleanfalseWhether the checkbox is in an error state.
errorMessagefalsestringThe error message to be displayed if the checkbox is in an error state.
colorSchemefalsePearlTheme["palette"]"primary"Active color palette of the checkbox.
spacingfalsePearlTheme["spacing"]"xs"The spacing between the checkbox and the label text.
shapefalse"square" | "circle""square"Shape of the checkbox.
checkedIconFamilyfalse "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.
checkedIconNamefalsestring"checkmark"Name of the icon when the checkbox is in checked state.
indeterminateIconFamilyfalse "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.
indeterminateIconNamefalsestring"remove-outline"Name of the icon when the checkbox is in indeterminate state.
checkedBackgroundColorfalsePearlTheme["palette"]"primary.500"The background color of the checkbox when it is in checked state.
checkedBorderColorfalsePearlTheme["palette"]"primary.500"The border color of the checkbox when it is in checked state
checkedBorderStartColorfalsePearlTheme["palette"]The border start color of the checkbox when it is in checked state.
checkedBorderEndColorfalsePearlTheme["palette"]The border end color of the checkbox when it is in checked state.
checkedBorderTopColorfalsePearlTheme["palette"]The border top color of the checkbox when it is in checked state.
checkedBorderLeftColorfalsePearlTheme["palette"]The border left color of the checkbox when it is in checked state.
checkedBorderRightColorfalsePearlTheme["palette"]The border right color of the checkbox when it is in checked state.
checkedBorderBottomColorfalsePearlTheme["palette"]The border bottom color of the checkbox when it is in checked state.
errorBackgroundColorfalsePearlTheme["palette"]The background color of the checkbox when it is in an error state.
errorBorderColorfalsePearlTheme["palette"]"danger.500"The border color of the checkbox when it is in an error state
errorBorderStartColorfalsePearlTheme["palette"]The border start color of the checkbox when it is in an error state.
errorBorderEndColorfalsePearlTheme["palette"]The border end color of the checkbox when it is in an error state.
errorBorderTopColorfalsePearlTheme["palette"]The border top color of the checkbox when it is in an error state.
errorBorderLeftColorfalsePearlTheme["palette"]The border left color of the checkbox when it is in an error state.
errorBorderRightColorfalsePearlTheme["palette"]The border right color of the checkbox when it is in an error state.
errorBorderBottomColorfalsePearlTheme["palette"]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 it.

Additional props#

NameRequiredTypeDefaultDescription
sizefalsePearlTheme.components.CheckBox["sizes"]"m"Size of all the children checkbox in the group.
variantfalsePearlTheme.components.CheckBox["variants"]"filled"Variant of all the children checkbox in the group.
valuefalseArray<string | number>Active value of the checkbox group.
defaultValuefalseArray<string | number>[]Default active value of the checkbox group.
onChangefalse(value: Array<string | number>) => voidMethod that gets invoked when the value of the checkbox group changes.
isDisabledfalsebooleanfalseWhether the checkbox group is disabled.
colorSchemefalsePearlTheme.palette"primary"Active color palette of all the children checkbox in the group.
shapefalse"square" | "circle""square"Shape of all the children checkbox in the group.

Default component Config#

export default {  parts: ["root", "box", "icon", "text", "errorText"],  baseStyle: {    root: {      my: "2xs",      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: "2xs",    },  },  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",  },};