The page navigation is complete. You may now navigate the page content as you wish.
Skip to main content

Checkbox

Gitea

A form element that allows users to select one or more items from a group of items.

An input of type "checkbox" is a form element that allows users to select one or more items from a list of individual items.

Usage

When to use

  • To allow users to check or uncheck an option or setting.
  • To allow users to select one or more options from a list.

When not to use

  • When only one choice can be selected, consider Radio buttons.
  • When checking or unchecking results in an immediate change, consider Toggle.

Layout

We recommend using vertical Checkbox groups, especially with short option lists.

Indeterminate state

Indeterminate states indicate a "partially checked" condition in nested structures or tables.

Do

Example of proper usage of the indeterminate state in the checkbox

Don’t

Example of misuse of the indeterminate state in the checkbox

Required and optional

For complex forms, indicate required fields. This is the most explicit and transparent method and ensures users don’t have to make assumptions. Read more about best practices for marking required fields in forms.

For shorter, simpler forms (e.g., login/signup and feedback requests), indicate optional fields instead.

Error validation

For error validation recommendations, refer to the Form patterns documentation.

How to use this component

There are three ways to use the Checkbox component, across the <i80-checkbox> and <i80-checkbox-group> elements:

  • the base control: an <i80-checkbox> with your own <input> written inside it
  • the field: an <i80-checkbox> with a label attribute — the <input> control, with label, helper text, and error messaging (in a wrapping container)
  • the group: an <i80-checkbox-group> around the fields — a legend (optional), a list of fields, and error messaging

The group

Use a group when there are multiple related options to choose from, or a single one that needs to be presented with an extra legend. If there’s a single choice and no need for an extra legend, use a single field.

The basic invocation creates:

  • a <fieldset> container.
  • a <legend> element, from the legend attribute.
  • a list of rendered checkbox fields.

Give each <i80-checkbox> in the group its own name.

<i80-checkbox-group legend="Valid datacenters">
  <i80-checkbox label="NYC1" name="demo-datacenter" value="NYC1"></i80-checkbox>
  <i80-checkbox label="DC1" name="demo-datacenter" value="DC1"></i80-checkbox>
  <i80-checkbox label="NYC2" name="demo-datacenter" value="NYC2"></i80-checkbox>
  <i80-checkbox label="SF1" name="demo-datacenter" value="SF1"></i80-checkbox>
</i80-checkbox-group>

Layout

To better fit your spacing requirements, choose between two different layout orientations with the layout attribute: vertical or horizontal.

<i80-checkbox-group legend="Valid datacenters" layout="vertical">
  <i80-checkbox label="NYC1" name="demo-datacenter" value="NYC1"></i80-checkbox>
  <i80-checkbox label="DC1" name="demo-datacenter" value="DC1"></i80-checkbox>
  <i80-checkbox label="NYC2" name="demo-datacenter" value="NYC2"></i80-checkbox>
  <i80-checkbox label="SF1" name="demo-datacenter" value="SF1"></i80-checkbox>
</i80-checkbox-group>
<i80-checkbox-group legend="Valid datacenters" layout="horizontal">
  <i80-checkbox label="NYC1" name="demo-datacenter" value="NYC1"></i80-checkbox>
  <i80-checkbox label="DC1" name="demo-datacenter" value="DC1"></i80-checkbox>
  <i80-checkbox label="NYC2" name="demo-datacenter" value="NYC2"></i80-checkbox>
  <i80-checkbox label="SF1" name="demo-datacenter" value="SF1"></i80-checkbox>
</i80-checkbox-group>

Required vs. optional

Use the required and optional attributes to add a visual indication that the field is “required” or “optional”.

<i80-checkbox-group legend="Methods" helper-text="All methods are applied by default unless specified." layout="horizontal" required>
  <i80-checkbox label="POST" name="demo-methods" value="POST" checked></i80-checkbox>
  <i80-checkbox label="GET" name="demo-methods" value="GET" checked></i80-checkbox>
  <i80-checkbox label="PUT" name="demo-methods" value="PUT" checked></i80-checkbox>
</i80-checkbox-group>
<i80-checkbox-group legend="Methods" helper-text="All methods are applied by default unless specified." layout="horizontal" optional>
  <i80-checkbox label="POST" name="demo-methods" value="POST" checked></i80-checkbox>
  <i80-checkbox label="GET" name="demo-methods" value="GET" checked></i80-checkbox>
  <i80-checkbox label="PUT" name="demo-methods" value="PUT" checked></i80-checkbox>
</i80-checkbox-group>

Validation

To indicate a field is invalid, provide an error message: the error attribute on the group.

<i80-checkbox-group legend="Valid datacenters" layout="horizontal" error="Error: you need to choose at least one datacenter.">
  <i80-checkbox label="NYC1" name="demo-datacenter" value="NYC1"></i80-checkbox>
  <i80-checkbox label="DC1" name="demo-datacenter" value="DC1"></i80-checkbox>
  <i80-checkbox label="NYC2" name="demo-datacenter" value="NYC2"></i80-checkbox>
  <i80-checkbox label="SF1" name="demo-datacenter" value="SF1"></i80-checkbox>
</i80-checkbox-group>

Field items

A group of Checkboxes is made of one or more checkbox fields: <i80-checkbox> elements. All the attributes that can be passed to a single field can be passed to the same items inside the group.

<i80-checkbox-group legend="Valid datacenters" layout="vertical">
  <i80-checkbox label="NYC1" name="datacenter1" value="NYC1" helper-text="CoreSite- 32 Avenue of the Americas"></i80-checkbox>
  <i80-checkbox label="DC1" name="datacenter2" value="DC1" helper-text="CoreSite- K Street" checked></i80-checkbox>
  <i80-checkbox label="NYC2" name="datacenter3" value="NYC2" helper-text="H5 Data Center - 325 Hudson Street" checked></i80-checkbox>
  <i80-checkbox label="SF1" name="datacenter4" value="SF1" helper-text="INAP - 650 Townsend Street"></i80-checkbox>
</i80-checkbox-group>

Group with a single choice

There may be use cases in which you need to create a Checkbox group that contains a single field element (e.g., to show the legend in a similar position for other control’s labels). 

<i80-checkbox-group legend="Visibility">
  <i80-checkbox label="Private" name="private" value="private" helper-text="Making a box private prevents users from accessing it unless given permission."></i80-checkbox>
</i80-checkbox-group>

The field

The field variant of the Checkbox component is to be used when there’s a single choice to make for the user. If there are multiple related choices, use a group.

The basic invocation requires a label: the label attribute. This creates:

  • a <label> element with a for attribute automatically associated with the input ID attribute.
  • an <input type="checkbox"> control with an automatically generated ID attribute.
<i80-checkbox label="Enable cost estimation" name="demo-cost-estimation"></i80-checkbox>

Input value

Pass a value to the checkbox input.

<i80-checkbox label="Enable cost estimation" name="demo-cost-estimation" value="enable"></i80-checkbox>

Checked

Use the standard HTML checked attribute to mark the input as checked.

<i80-checkbox label="Enable cost estimation" name="demo-cost-estimation" checked></i80-checkbox>

Validation

To indicate a field is invalid, provide an error message: the error attribute.

<i80-checkbox label="I approve the changes." name="demo-approve-change" error="Error: it is necessary to explicitly approve the changes to continue."></i80-checkbox>

Custom control ID

If needing a custom ID for the control instead of the one automatically generated by the component, write the <input> yourself inside the element with that id.

In this case all the internal references (id/for/aria-describedby) between the different parts of the field are still automatically generated and will use the custom ID provided.

<i80-checkbox label="Enable cost estimation" helper-text="With this option enabled you will receive an approximate cost estimation.">
  <input type="checkbox" name="demo-cost-estimation" id="my-control">
</i80-checkbox>

HTML native attributes

The element passes name, value, checked, required, disabled and readonly on to the <input> it creates. For any other native behavior, write the <input> yourself inside the element and it is kept as it is, with all its attributes.

<i80-checkbox label="Enable cost estimation" name="demo-cost-estimation"></i80-checkbox>

The base control

The base control is intended for rare cases where the field or the group can’t be used and a custom implementation is needed. Most of the details for the field also apply to it, but see the Component API for more details.

Consumer responsibility

An <i80-checkbox> without a label does not come with built-in accessibility functionality. It is the responsibility of the product team to ensure the implementation is conformant.

Write the <input type="checkbox"> inside the element with its own aria-label.

<i80-checkbox>
  <input type="checkbox" name="demo-cost-estimation" value="enable" aria-label="Enable cost estimation">
</i80-checkbox>

Attributes

<i80-checkbox> renders this component. Everything it understands:

Attribute Values Default Notes
label, helper-text, error, invalid, name, value, checked, required, optional, disabled, readonly On i80-checkbox, i80-radio and i80-toggle.
legend, helper-text, error, required, optional On i80-checkbox-group, i80-radio-group and i80-toggle-group.
layout vertical · horizontal vertical On i80-checkbox-group, i80-radio-group and i80-toggle-group.
name text On i80-radio-group: given to radios without a name.

The tag keeps any native element you write inside it, so a server-rendered form, link or button works as it is. See Web Components for loading i80.js and the reference for these examples running.

Anatomy

A single checkbox

Checkbox field anatomy

Element Usage
Base control Required
Label Required
Helper text Optional
Error message Triggered by system

A group of checkboxes

Checkbox group anatomy

Element Usage
Legend Optional
Helper text Optional
Fields At least one is required
Error message Triggered by system

States

Checkbox state example

For general content recommendations, refer to the Primitives documentation.

Conformance rating

A group of checkboxes

Conformant

<i80-checkbox-group> is conformant when used as directed: it renders a real <fieldset> and the legend attribute becomes its <legend>, so a screen reader reads the group’s name before each choice.

A single checkbox

Conformant

<i80-checkbox> with a label is conformant: the label is a real <label for> pointing at the <input type="checkbox">, so clicking the text ticks the box and the control has an accessible name.

A checkbox without a label

Conditionally conformant

A checkbox is not conformant until it has an accessible name. If you leave the label attribute off — because the name is already in a table header or a heading nearby — put an aria-label on the element instead, or write your own <label for="…"> and <input> inside the tag.

Known issues

The helper text and the error are announced through aria-describedby, and a screen reader reads only their text. A link inside them is not announced as a link, so a keyboard user has no way to reach it from the announcement. Put links in the surrounding page content rather than in a label, helper text or error message.

Applicable WCAG Success Criteria

This section is for reference only, some descriptions have been truncated for brevity. This component intends to conform to the following WCAG Success Criteria:

  • 1.3.1 Info and Relationships (Level A):
    Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
  • 1.3.2 Meaningful Sequence (Level A):
    When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined.
  • 1.3.4 Orientation (Level AA):
    Content does not restrict its view and operation to a single display orientation, such as portrait or landscape.
  • 1.3.5 Identify Input Purpose (Level AA):
    The purpose of each input field collecting information about the user can be programmatically determined when the input field serves a purpose identified in the Input Purposes for User Interface Components section; and the content is implemented using technologies with support for identifying the expected meaning for form input data.
  • 1.4.1 Use of Color (Level A):
    Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element.
  • 1.4.10 Reflow (Level AA):
    Content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions.
  • 1.4.11 Non-text Contrast (Level AA):
    The visual presentation of the following have a contrast ratio of at least 3:1 against adjacent color(s): user interface components; graphical objects.
  • 1.4.12 Text Spacing (Level AA):
    No loss of content or functionality occurs by setting all of the following and by changing no other style property: line height set to 1.5; spacing following paragraphs set to at least 2x the font size; letter-spacing set at least 0.12x of the font size, word spacing set to at least 0.16 times the font size.
  • 1.4.3 Minimum Contrast (Level AA):
    The visual presentation of text and images of text has a contrast ratio of at least 4.5:1
  • 1.4.4 Resize Text (Level AA):
    Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality.
  • 2.4.6 Headings and Labels (Level AA):
    Headings and labels describe topic or purpose.
  • 2.4.7 Focus Visible (Level AA):
    Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.
  • 3.2.1 On Focus (Level A):
    When any user interface component receives focus, it does not initiate a change of context.
  • 3.2.2 On Input (Level A):
    Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.
  • 3.2.4 Consistent Identification (Level AA):
    Components that have the same functionality within a set of Web pages are identified consistently.
  • 3.3.2 Labels or Instructions (Level A):
    Labels or instructions are provided when content requires user input.
  • 4.1.2 Name, Role, Value (Level A):
    For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.

0.1.0

Første i80-version (fork af upstream, se core/UPSTREAM.md).

Related

On this page: