Amplify UI

CheckboxField

CheckboxField allows users to mark items as selected.

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.

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

<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

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}' },
        },
      },
    },
  },
};

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

Icons

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

ClassDescription
amplify-checkboxfieldTop 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" />;

Amplify open source software, documentation and community are supported by Amazon Web Services.

© 2024 Amazon Web Services, Inc. and its affiliates. All rights reserved. View the site terms and privacy policy.

Flutter and the related logo are trademarks of Google LLC. We are not endorsed by or affiliated with Google LLC.