CheckboxField

CheckboxField allows users to mark items as selected.

ARIA pattern Theme source React source Feedback

Demo

Usage

Import the CheckboxField primitive.

import * as React from 'react';
import { CheckboxField } from '@aws-amplify/ui-react';

export const DefaultCheckboxFieldExample = () => (
  <CheckboxField label="Subscribe" name="subscribe" value="yes" />
);

Controlled component

import * as React from 'react';

import { CheckboxField } from '@aws-amplify/ui-react';

export const CheckboxFieldControlledExample = () => {
  const [checked, setChecked] = React.useState(false);
  return (
    <CheckboxField
      name="subscribe-controlled"
      value="yes"
      checked={checked}
      onChange={(e) => setChecked(e.target.checked)}
      label="Subscribe"
    />
  );
};

Sizes

Use the size prop to change the SelectField size. Available options are small, large, and none (default).

import * as React from 'react';
import { CheckboxField, Flex } from '@aws-amplify/ui-react';

export const CheckboxFieldSizesExample = () => (
  <Flex>
    <CheckboxField
      label="Subscribe"
      name="subscribe"
      value="yes"
      size="small"
    />
    <CheckboxField label="Subscribe" name="subscribe" value="yes" />
    <CheckboxField
      label="Subscribe"
      name="subscribe"
      value="yes"
      size="large"
    />
  </Flex>
);

Value

The value associated with the checkbox name in form data, used when submitting an HTML form. If a checkbox is unchecked when its form is submitted, its value will not be submitted. See MDN.

import { CheckboxField, Button } from '@aws-amplify/ui-react';
import * as React from 'react';

export const CheckboxFieldValueExample = () => {
  const onSubmit = (event) => {
    event.preventDefault();
    alert(event.target.subscribe.value);
  };
  return (
    <form onSubmit={onSubmit}>
      <CheckboxField label="Subscribe" name="subscribe" value="yes" />
      <Button type="submit">Submit</Button>
    </form>
  );
};

In this example, we've got a name of subscribe, and a value of yes. When the form is submitted, the data name/value pair will be subscribe=yes.

State

Disabled

A disabled checkbox will be not be focusable not mutable. A checked checkbox could also be disabled but it will not be submitted with form data.

import * as React from 'react';

import { CheckboxField, Flex } from '@aws-amplify/ui-react';

export const CheckboxFieldDisabledExample = () => {
  return (
    <Flex>
      <CheckboxField
        label="Subscribe"
        name="subscribe"
        value="yes"
        isDisabled
      />
      <CheckboxField
        label="Subscribe"
        name="subscribe"
        value="yes"
        defaultChecked
        isDisabled
      />
    </Flex>
  );
};

Indeterminate

In addition to the checked and unchecked states, there is a third state a checkbox can be in: indeterminate. This is a state in which it's impossible to say whether the item is toggled on or off.

All Pets

Cat

Dog

import * as React from 'react';

import { CheckboxField, Flex, View } from '@aws-amplify/ui-react';

export const CheckboxFieldIndeterminateExample = () => {
  const [checkedItems, setCheckedItems] = React.useState([false, false]);
  const checkedItemsRef = React.useRef(null);
  const allChecked = checkedItems.every(Boolean);
  const isIndeterminate = checkedItems.some(Boolean) && !allChecked;

  if (isIndeterminate) {
    checkedItemsRef.current = [...checkedItems];
  }
  const handleAllPetsChange = () => {
    if (isIndeterminate) {
      setCheckedItems([true, true]);
    } else if (allChecked) {
      setCheckedItems([false, false]);
    } else if (checkedItemsRef.current) {
      setCheckedItems(checkedItemsRef.current);
    } else {
      setCheckedItems([true, true]);
    }
  };

  const handleCatChange = (e) => {
    const newCheckedItems = [e.target.checked, checkedItems[1]];
    if (!newCheckedItems.some(Boolean) || newCheckedItems.every(Boolean)) {
      checkedItemsRef.current = null;
    }
    setCheckedItems(newCheckedItems);
  };

  const handleDogChange = (e) => {
    const newCheckedItems = [checkedItems[0], e.target.checked];
    if (!newCheckedItems.some(Boolean) || newCheckedItems.every(Boolean)) {
      checkedItemsRef.current = null;
    }
    setCheckedItems(newCheckedItems);
  };

  return (
    <Flex direction="column" gap="0">
      <CheckboxField
        name="all-pets"
        label="All Pets"
        value="allPets"
        checked={allChecked}
        isIndeterminate={isIndeterminate}
        onChange={handleAllPetsChange}
      />
      <View paddingLeft="25px">
        <CheckboxField
          name="cat"
          label="Cat"
          value="cat"
          checked={checkedItems[0]}
          onChange={handleCatChange}
        />
        <CheckboxField
          name="dog"
          label="Dog"
          value="dog"
          checked={checkedItems[1]}
          onChange={handleDogChange}
        />
      </View>
    </Flex>
  );
};

Validation error

Use the hasError and errorMessage props to mark a CheckboxField as having an validation error.

import * as React from 'react';
import { CheckboxField, Button } from '@aws-amplify/ui-react';

export const CheckboxFieldWithErrorExample = () => {
  const [checked, setChecked] = React.useState(false);
  const [hasError, setHasError] = React.useState(false);

  const onSubmit = (event) => {
    event.preventDefault();
    if (!checked) {
      setHasError(true);
    } else {
      setHasError(false);
      alert(`success`);
    }
  };

  return (
    <form onSubmit={onSubmit}>
      <CheckboxField
        label="I agree to the terms and conditions"
        name="toc"
        value="yes"
        checked={checked}
        hasError={hasError}
        errorMessage="Please agree to the terms and conditions"
        onChange={(e) => setChecked(e.target.checked)}
      />
      <Button type="submit">Submit</Button>
    </form>
  );
};

Accessibility / Label behavior

import * as React from 'react';
import { CheckboxField, Flex } from '@aws-amplify/ui-react';

export const CheckboxFieldLabelHiddenExample = () => (
  <Flex>
    <CheckboxField label="Subscribe" name="subscribe" value="yes" />
    <CheckboxField
      label="Subscribe"
      name="subscribe"
      value="yes"
      labelHidden={true}
    />
  </Flex>
);

Standard HTML attributes

The CheckboxField will accept any of the standard HTML attributes that a <input> element accepts. Standard <input> attributes can be found in the MDN Documentation

Subscribe to our newsletter

<CheckboxField label="Subscribe to our newsletter" name="subscribe" value="yes" />

Styling

Theme

You can customize the appearance of all CheckboxField components in your application with a Theme.

CheckboxField Theme Source

Disabled example

import { CheckboxField, ThemeProvider, Theme } from '@aws-amplify/ui-react';

const theme: Theme = {
  name: 'checkbox-theme',
  tokens: {
    components: {
      checkbox: {
        button: {
          color: { value: '{colors.yellow.40}' },
          _focus: {
            outlineColor: { value: '{colors.blue.40}' },
            borderColor: { value: '{colors.red.40}' },
          },
        },
        icon: {
          backgroundColor: { value: '{colors.secondary.80}' },
        },
        label: {
          color: { value: '{colors.purple.80}' },
          _disabled: {
            color: { value: '{colors.purple.60}' },
          },
        },
      },
    },
  },
};

export const CheckboxFieldThemeExample = () => (
  <ThemeProvider theme={theme} colorMode="light">
    <CheckboxField label="Subscribe" name="subscribe" />
    <CheckboxField
      label="Disabled example"
      name="disabledExample"
      value="yes"
      isDisabled={true}
    />
  </ThemeProvider>
);

Icons

Cat

Dog

import { CheckboxField, Flex, IconsProvider } from '@aws-amplify/ui-react';
import { HiMinus, HiCheck } from 'react-icons/hi';

export const CheckboxFieldIconExample = () => (
  <IconsProvider
    icons={{
      checkbox: {
        checked: <HiCheck />,
        indeterminate: <HiMinus />,
      },
    }}
  >
    <Flex direction="column">
      <CheckboxField name="cat" label="Cat" value="cat" defaultChecked={true} />
      <CheckboxField name="dog" label="Dog" value="dog" isIndeterminate />
    </Flex>
  </IconsProvider>
);

Target classes

Class	Description
`amplify-checkboxfield`	Top level element that wraps the CheckboxField primitive

--amplify-components-checkboxfield-align-content
--amplify-components-checkboxfield-align-items
--amplify-components-checkboxfield-flex-direction
--amplify-components-checkboxfield-justify-content

Global styling

To override styling on all Checkbox icons, you can set the Amplify CSS variables or use the built-in .amplify-checkbox__icon class.

/* styles.css */
:root {
  --amplify-components-checkbox-icon-background-color: var(
    --amplify-colors-blue-80
  );
}
/* OR */
.amplify-checkbox__icon {
  background-color: var(--amplify-colors-blue-80);
}

Local styling

To override styling on a specific Checkbox, you can use (in order of increasing specificity): a class selector, data attributes, or style props.

Using a class selector:

/* styles.css */
.custom-checkbox .amplify-checkbox {
  align-items: flex-start;
  flex-direction: column-reverse;
}

import { CheckboxField } from '@aws-amplify/ui-react';
import './styles.css';

<CheckboxField
  label="Subscribe"
  name="subscribe"
  value="yes"
  className="custom-checkbox"
/>;

Using data attributes:

/* styles.css */

.amplify-checkbox__icon[data-checked='true'] {
  background-color: var(--amplify-colors-purple-80);
}

import { CheckboxField } from '@aws-amplify/ui-react';
import './styles.css';

<CheckboxField label="Subscribe" name="subscribe" value="yes" />;

Using style props:

import { CheckboxField } from '@aws-amplify/ui-react';

<CheckboxField label="Subscribe" name="subscribe" value="yes" gap="1rem" />;