The Checkbox component renders a checkbox input, which allows selecting one or more options from a group of options.

For a standardized group of options, Checkbox should be used with the CheckboxGroup component.

Importing

The component can be imported via:

import { Checkbox } from '@customerio/pluma-components/react';

Usage

When using a standalone Checkbox, at a minimum you will need to supply:

  • an isChecked state
  • a handler for state changes (either onCheckedChange or onChange)
  • a label
import { Checkbox } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
	const [isChecked, setIsChecked] = useState(false);

	return <Checkbox
		value="checkbox_value"
		label="Default checkbox"
		isChecked={isChecked}
		onCheckedChange={(checked) => {
			setIsChecked(checked);
		}}
	/>
}

More examples of available props:

<Checkbox
  value="enabled_checkbox"
  label="Enabled Checkbox"
  isChecked={true}
  onCheckedChange={() => {}}
/>

<Checkbox
  value="unchecked_checkbox"
  label="Unchecked checkbox"
  isChecked={false}
  onCheckedChange={() => {}}
/>

<Checkbox
  value="disabled_checkbox"
  label="Disabled checkbox"
  isChecked={false}
  isDisabled={true}
  onCheckedChange={() => {}}
/>

Labels

A Checkbox must always have an associated label. The component accepts a label string prop, which renders the label next to the checkbox.

Alternatively, ariaLabelledby may be used to associate the checkbox with a label elsewhere in the DOM. To make sure the association is set up both ways, it's recommended to also set for on the label, pointing to an id on the checkbox:

import { Checkbox, Box } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [checked, setChecked] = useState(false);

  return (
    <>
      <Box
        as="label"
        id="my_label_id"
        htmlFor="my_aria_checkbox"
      >
        Accept terms and conditions
      </Box>
      <Checkbox
        id="my_aria_checkbox"
        ariaLabelledby="my_label_id"
        isChecked={checked}
        onCheckedChange={(checked) => setChecked(checked)}
      />
    </>
  );
}

Finally, the ariaLabel prop can be used if no other element is suitable for a label.

Indeterminate state

isIndeterminate can be used to show partially selected states. For example:

import { Checkbox, Box } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [checkboxItems, setCheckboxItems] = useState([
    { value: 'email', label: 'Email' },
    { value: 'inapp', label: 'In-app' },
    { value: 'sms', label: 'SMS' },
  ]);

  const [values, setValues] = useState(['inapp']);

  const onCheckedChange = (checked, e) => {
    const value = e.currentTarget.value;
    const currentState = values;
    console.log({value, checked, currentState});

    if (value === 'messaging_types') {
      if (checked) {
        setValues(checkboxItems.map((i) => i.value));
      } else {
        setValues([]);
      }
    } else {
      if (checked) {
        setValues([...currentState, value]);
      } else {
        setValues(currentState.filter((v) => v !== value));
      }
    }
  };

return (
  <>
    <Checkbox
      label="Messaging types"
      value="messaging_types"
      isChecked={values.length === checkboxItems.length}
      isIndeterminate={values.length > 0 && values.length < checkboxItems.length}
      onCheckedChange={onCheckedChange}
    />

    <Box display="flex" flexDirection="column" gap="100" mt="100" pl="200">
      {checkboxItems.map((item) => (
        <Checkbox
          key={item.value}
          label={item.label}
          value={item.value}
          isChecked={values.includes(item.value)}
          onCheckedChange={onCheckedChange}
        />
      ))}
    </Box>
    </>
  )
}

Customizing labels

If a string label is not sufficient, a component can be used to render the label.

In React, the label prop accepts any ReactNode.

import { Checkbox, Icon } from '@customerio/pluma-components/react';
import { useState } from 'react';

export default function Example() {
  const [isChecked, setIsChecked] = useState(false);

  return <Checkbox
    label={<>Custom label <Icon name="campaigns" isInline={true} size="sm" /></>}
    isChecked={isChecked}
    onCheckedChange={(checked) => {
      setIsChecked(checked);
    }}
  />
}

API

Element (or elements) that describe the form field. Also used for error messages, as aria-errormessage isn't supported in all assistive technologies: https://a11ysupport.io/tech/aria/aria-errormessage_attribute

String value that labels the form field.

Element (or elements) that label the form field.

A description for the field, providing additional context or hints.

An error message associated with the form field. Boolean: Ember-only. If the error named block is used, this prop can be set to true to indicate an error is present, which will make the error block render.

An optional id to be assigned to the input element. Also used to generate ids for labels and error messages. If one isn't provided, it will be generated.

Whether the checkbox is in the "checked" state. This argument is not required when inside a CheckboxGroup

Whether the form field is disabled.

Whether the checkbox is in the "indeterminate" state

Whether the form field is in an invalid state.

The label text to show with the form field.

The name shared by checkboxes in the same group. This argument is not required when inside a CheckboxGroup

The change event handler for the input element. Fired when a checkbox is checked or unchecked. In React, the event is a React SyntheticEvent; in Ember it's a native change event.

Whether to allow browser autofill and password managers. When false (default), adds attributes to disable password managers (1Password, LastPass, Bitwarden, Dashlane). Set to true for fields where autofill is desired (e.g., email, password, address fields).

Whether the generated description id should be included in the input's aria-describedby attribute. Disable this when a label`` tag surrounds the input as well as it's description text, for example in an OptionCard` component.

Whether the generated label id should be included in the input's aria-labelledby attribute. Disable this when the label tag surrounds the input as well as it's label text, for example in an OptionCard component.

Whether the label text should be truncated (with ellipsis) if it overflows.

By default, form elements will throw an error if no label or aria-label is provided. Disable this to suppress the error, for example when building a custom form element, and you want to handle labeling yourself.

Additional classes to be applied to the description element.

Additional classes to be applied to the error element.

Additional classes to be applied to the field node.

Additional classes to be applied to the footer element.

Ember-only: this is used internally to detect whether a label named block is present, and to ignore empty label props if so.

Additional classes to be applied to the input node.

Sets the size attribute on the input element. This controls the visible width of the input in characters.

Whether the component should render with "legacy" styles.

Additional classes to be applied to the label node.

The value associated with this checkbox

Whether to apply the center-baseline variant.