Checkbox

const CheckboxChecked = () => {
  const [checked, setChecked] = React.useState(true);
  return (
    <Checkbox
      checked={checked}
      id="blm"
      value="blm"
      name="blm"
      onChange={(event) => {
        setChecked(event.target.checked);
      }}
    >
      Enable SSL certificate validation
    </Checkbox>
  );
};

render(
  <CheckboxChecked />
)

The Checkbox and Checkbox Group are used to enable binary choices. These can either be used for an individual choice or to form a collection of choices.

Checkbox groups are used when you have multiple binary choices to make but all choices belong to a single group or field. For example, choosing capabilities when searching for a Phone Number to provision from Twilio. By placing them in a group, users should be able to clearly understand which options make up the collection and also how those options are related to each other.

• Checkbox groups must have a group legend that describes the collection.
  • The label should be visible.
  • The label may be visually hidden or provided via aria-label on the group component if the entire form is just a single checkbox group with no other form elements. The grouping should be visually implicit, but a description still needs to be provided for assistive technology.

Use a checkbox to present a user with a binary (e.g. on/off) choice that is part of a form. A checkbox should not be used to apply a user's choice instantly. In that case, such as enabling a system feature, you should consider using the Switch component.

• A checkbox must have a visible label that is in close proximity to the control
• HTML checkboxes don't natively support the required attribute. In cases where a checkbox is required to be checked:
  • Display a required indicator
  • Ensure the label text includes wording that successfully describes the requirement to the user that they should check the box
• When in an error state, display an inline error message below the checkbox or checkbox group that clearly describes the error along with an icon that depicts the severity.
• When displaying additional content based on checking a checkbox, be sure that the new content appears after the checkbox so that it is naturally discoverable by assistive technology users.

The checkbox can either be controlled, meaning there is an external state that determines if the checkbox is checked or not, or uncontrolled, meaning the checkbox manages its own state.

To make an uncontrolled checkbox, you do not pass the checked or onChange props. If you need the checkbox to be checked by default, use the defaultChecked prop.

const UncontrolledCheckbox = () => {
  return (
    <Checkbox
      id="uncontrolled"
      value="uncontrolled"
      name="uncontrolled"
      defaultChecked
    >
      I am an uncontrolled checkbox
    </Checkbox>
  );
};

render(
  <UncontrolledCheckbox />
)

To make a controlled checkbox, you must pass the checked and onChange props. You cannot use the defaultChecked prop in a controlled checkbox.

const ControlledCheckbox = () => {
  const [checked, setChecked] = React.useState(true);
  return (
    <Checkbox
      id="controlled"
      value="controlled"
      name="controlled"
      checked={checked}
      onChange={(event) => {
        setChecked(event.target.checked);
      }}
    >
      I am a controlled checkbox
    </Checkbox>
  );
};

render(
  <ControlledCheckbox />
)

A checkbox is always displayed next to a visible label.

const CheckboxChecked = () => {
  const [checked, setChecked] = React.useState(true);
  return (
    <Checkbox
      checked={checked}
      id="blm"
      value="blm"
      name="blm"
      onChange={(event) => {
        setChecked(event.target.checked);
      }}
    >
      Enable SSL certificate validation
    </Checkbox>
  );
};

render(
  <CheckboxChecked />
)

In cases where the checkbox requires additional context, you can display this information as help text below the checkbox control and label. This can help keep checkbox labels concise. In order to maintain styling consistency, be sure to use the helpText prop here instead of using the Help Text component.

<Checkbox id="enabled" value="enabled" name="enabled" helpText="Determines if certificate validation is performed on all Twilio originated requests">
  Enable SSL certificate validation
</Checkbox>

When a checkbox is required to be checked, a required indicator should be displayed alongside the label. The label text should also be written in such a way that this requirement is clear to the user.

<Checkbox id="delete" value="delete" name="delete" required>
  Confirm this message should be deleted
</Checkbox>

Multiple checkboxes and their labels are grouped together with a common group component. The group legend must be the first element inside the group. It must appear before any checkboxes or other content.

<CheckboxGroup
  name="desktop"
  legend="Select the clients you would like to test."
>
  <Checkbox id="apple_mail" value="apple_mail">
    Apple Mail
  </Checkbox>
  <Checkbox id="outlook" value="outlook">
    Outlook
  </Checkbox>
</CheckboxGroup>

You can provide additional information about the group with the use of help text. Help text can appear after the group label but before the first group member. Each item in the group may also provide their own, individual help text.

<CheckboxGroup
  name="ad_partners"
  legend="Which ad partnes would you like to advertise on?"
  helpText="Select at least 1 ad partner to create a campaign."
>
  <Checkbox
    id="facebook"
    value="facebook"
    helpText={
      <Text as="span" color="currentColor">
        Questions? <Anchor href="http://paste.twilio.com">Click here to learn more</Anchor>.
      </Text>
    }
  >
    Facebook
  </Checkbox>
  <Checkbox
    id="instagram"
    value="instagram"
    helpText={
      <Text as="span" color="currentColor">
        Questions? <Anchor href="http://paste.twilio.com">Click here to learn more</Anchor>.
      </Text>
    }
  >
    Outlook
  </Checkbox>
</CheckboxGroup>

<CheckboxDisclaimer id="disclaimer" value="disclaimer" name="disclaimer">
  I declare the information provided above is accurate. I acknowledge that Twilio will process the information provided above for the purpose of identity verification, and will be sharing it with my local telecomm providers or authorities where required by local law. I understand that Twilio phone numbers may be taken out of service for inaccurate or false information.
</CheckboxDisclaimer>

To internationalize a checkbox, simply pass different text to the checkbox and checkbox group. The only exception to this is the required dot in the legend of a required checkbox group. To change the required dot's text, use the i18nRequiredLabel prop.

<CheckboxGroup
  name="days"
  legend="Jours préférés"
  i18nRequiredLabel="(requis)"
  required
>
  <Checkbox id="monday" value="monday">
    lundi
  </Checkbox>
  <Checkbox id="tuesday" value="tuesday">
    mardi
  </Checkbox>
  <Checkbox id="wednesday" value="wednesday">
    mercredi
  </Checkbox>
  <Checkbox id="thursday" value="thursday">
    jeudi
  </Checkbox>
  <Checkbox id="friday" value="friday">
    vendredi
  </Checkbox>
</CheckboxGroup>

The default state of a checkbox indicates that the control is unchecked, or not selected. When a checkbox is clicked or the spacebar is pressed when focused, the checkbox will become checked. Doing so again will place the checkbox back into the unchecked state. A checkbox can be placed into a pre-checked state by setting the checked property.

The third state a checkbox can appear in is the indeterminate state. This is to indicate that a checkbox is neither checked nor unchecked. This is useful when dealing with related groups of checkboxes that have a dependent relationship, for example, a select all feature.

const Results = () => {
  const [checkedItems, setCheckedItems] = React.useState([true, false]);

  const allChecked = checkedItems.every(Boolean);
  const indeterminate = checkedItems.some(Boolean) && !allChecked;

  const checkboxRef = React.createRef();

  return (
    <CheckboxGroup isSelectAll name="results" legend="Include in Results">
      <Checkbox
        id="select_all"
        checked={allChecked}
        indeterminate={indeterminate}
        ref={checkboxRef}
        onChange={e => setCheckedItems([e.target.checked, e.target.checked])}
      >
        Select all
      </Checkbox>
      <Checkbox
        id="identity"
        checked={checkedItems[0]}
        onChange={e => setCheckedItems([e.target.checked, checkedItems[1]])}
      >
        Identity carrier
      </Checkbox>
      <Checkbox
        id="caller_name"
        checked={checkedItems[1]}
        onChange={e => setCheckedItems([checkedItems[0], e.target.checked])}
      >
        Caller name
      </Checkbox>
    </CheckboxGroup>
  );
};

render(
  <Results />
)

Use a disabled checkbox to indicate that a particular option cannot be interacted with or can be safely ignored.

<Checkbox
  id="hammer"
  value="hammer"
  name="hammer"
  disabled
  checked
>
  Can't touch this
</Checkbox>

When at least one item from the checkbox group is required, a required indicator should be displayed alongside the group legend. The group help text should be used to describe the requirement.

<CheckboxGroup
  name="email"
  legend="Email Notifications"
  helpText="We can remind you when one of your Buffer is looking a little empty."
  required
>
  <Checkbox id="empty_buffer" value="empty_buffer">
    Empty buffer
  </Checkbox>
  <Checkbox id="newsletter" value="newsletter">
    Newsletter
  </Checkbox>
  <Checkbox id="update_failures" value="update_failures">
    Update failures
  </Checkbox>
</CheckboxGroup>

Use a disabled checkbox group to indicate that all options cannot be interacted with, with each checkbox individually disabled.

<CheckboxGroup
  name="capabilities"
  legend="Capabilities"
  orientation="horizontal"
  disabled
>
  <Checkbox id="voice" value="voice">
    Voice
  </Checkbox>
  <Checkbox id="fax" value="fax">
    Fax
  </Checkbox>
  <Checkbox id="sms" value="sms">
    SMS
  </Checkbox>
</CheckboxGroup>

If the selected options don't pass the group validation requirements, display an inline error message below the checkbox group.

<CheckboxGroup
  name="api"
  legend="API Key Permissions"
  errorText="Select at least one option."
>
  <Checkbox id="full_access" value="full_access">
    Full access
  </Checkbox>
  <Checkbox id="restricted_access" value="restricted_access">
    Restricted access
  </Checkbox>
</CheckboxGroup>

Checkboxes and Checkbox Groups must have a visible label.

• Aim for no more than 3 words. If the label must be longer and space is limited, wrap the label.
• Structure each checkbox label similarly. For example, make each checkbox a noun.
• Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

Checkbox labels should reflect what happens if the box is checked. Avoid situations where the user must check a box to negate something. For example, "Don't send message."

Avoid constructing the legend and label text to read as a sentence.

Use Help Text to give additional context and provide enough information to avoid errors. Consider using Help Text to indicate to users that they can select multiple options. Limit Help Text to 1-2 sentences.

To support internationalization, avoid starting a sentence with the legend and using the field to finish it since sentence structures vary across languages. For example, use "Phone Number capabilities", not "Phone Number capabilities include:".

Validate form fields on form submission. Don't validate each item in a group, treat validation on the group as a whole.

Use inline error text to explain how to fix an error. Because space is typically limited, focus the error text on how users can fix the issue. For additional guidance on how to compose error messages, refer to the error state pattern.