Checkbox ​

Checkboxes are most commonly used to give users a way to make a range of sections (zero, one, or multiple). They may also be used as a way to have users indicate they agree to specific terms and services.

Usage ​

[]

<script lang="ts" setup>
import { ref } from 'vue'; 
import { FormLayout, Checkbox } from '@returnless/focus-ui';

const checkboxValues = ref([]);  
</script>

<template>
  <FormLayout>
    <Checkbox
      v-model="checkboxValues"
      value="comments"
      label="Comments"
      help-text="Get notified when someones posts a comment on a posting." />
    <Checkbox
      v-model="checkboxValues"
      value="candidates"
      label="Candidates"
      help-text="Get notified when a candidate applies for a job." />
    <Checkbox
      v-model="checkboxValues"
      value="offers"
      label="Offers"
      help-text="Get notified when a candidate accepts or rejects an offer." />
  </FormLayout>
</template>

Checkbox group ​

When you have a list of checkboxes that are closely related, consider using a CheckboxGroup to make it easier for users to scan the list and understand the relationship between the options.

[]

<script lang="ts" setup>
import { ref } from 'vue'; 
import { Checkbox, CheckboxGroup } from '@returnless/focus-ui';

const checkboxValues = ref([]);  
</script>

<template>
  <CheckboxGroup label="Form management">
    <Checkbox
      v-model="checkboxValues"
      value="update-forms"
      label="Update forms" />
    <Checkbox
      v-model="checkboxValues"
      value="read-forms"
      label="Read forms" />
    <Checkbox
      v-model="checkboxValues"
      value="edit-forms"
      label="Edit forms" />
    <Checkbox
      v-model="checkboxValues"
      value="delete-forms"
      label="Delete forms" />
  </CheckboxGroup>
</template>

Indeterminate state ​

Use the indeterminate prop to indicate that a checkbox is in an indeterminate state. This is useful when you have a list of checkboxes and some, but not all, of the checkboxes are selected.

<script lang="ts" setup>
import { ref } from 'vue'; 
import { Checkbox } from '@returnless/focus-ui';

const indeterminateCheckboxValue = ref(true);  
</script>

<template>
    <Checkbox
      v-model="indeterminateCheckboxValue"
      value="indeterminate-checkbox"
      indeterminate
      label="Indeterminate checkbox" />
  true
</template>

Best practices ​

Checkboxes should:

• Work independently of each other. Selecting one checkbox shouldn't change the selection status of another checkbox in the list The exception is when a checkbox is used to make a bulk selection of multiple items.
• Be framed positively. For example, say "Publish form" instead of "Hide form".
• Always have a label when used to activate or deactivate a setting.
• Be listed according to logical order, whether it's alphabetical, numerical, time-based, or some other clear system.
• Link to more information or include a subtitle as required to provide more explanation. Don't rely on tooltips to explain a checkbox.

Content guidelines ​

List that use checkboxes should:

• Start with a capital letter.
• Not use commas or semicolons at the end of each item.
• In the rare case where the checkbox is asking users to agree to terms or services, use the first person.

Accessibility ​

Screen readers convey the state of the checkboxes automatically.

• Use the disabled prop to apply the HTML disabled attribute to the checkbox <input>. This prevents users from being able to interact with the checkbox, and conveys its inactive state to assistive technologies.
• Use the id prop to provide a unique id attribute value for the checkbox. If an id isn't provide, the component generates one automatically. All checkboxes must have a unique id value to work correctly with assistive technologies.
• Setting checked="ideterminate" conveys the state of the checkbox as aria-checked="mixed".
• Setting the ariaControls prop conveys the ID of the element whose contents or presence are controlled by the checkbox to screen reader users with the aria-controls attribute.

Labeling ​

• The required label prop conveys the purpose of the checkbox to all users.
• Use the labelHidden prop to visually hide the label but make it available to assistive technologies.
• When you provide help text via the helpText prop or an inline error message via the error prop, the help or error content is conveyed to screen reader users with the aria-describedby attribute.

Keyboard support ​

• Move focus to each checkbox using the tab key (or shift + tab when tabbing backwards).
• To interact with the checkbox when it has keyboard focus, press the space key.