Anatomy
- Prefix (optional): Indicates the order of the checklist item
- Checkbox: Can be selected or unselected to indicate the status of the checklist item
- Text link: Navigates to the target location
Subcomponents
See the usage guidelines for checkbox
See the usage guidelines for text link
See the usage guidelines for button bare
See the usage guidelines for button iconic
See the usage guidelines for button
See the usage guidelines for textarea
See the usage guidelines for input
Usage
Use checklist to select one or more separate items from an ordered or unordered list of checkboxes. If configured, a user can add, edit, or remove items in the checklist or drag and drop them to reorder the list.
Configurations
Learn how to customize checklist by configuring the available properties.
Prefixes
You can configure checklist to contain numeric or alphabetic prefixes in front of the checkbox items. Use this when the checklist items need to be ordered.
Required field indicator
To require a user to complete a checklist item or option, enable the Required field indicator. When this option is enabled, users receive a message if they attempt to submit a form and have not completed the required field(s). When a field is configured as required, an asterisk (*) symbol appears to the right of the field label.
Checkboxes
You can configure checkboxes to appear as selected or not selected by default. You can also configure the checkboxes to display in a specific list order.
Links
You can configure checklist to display links for any checklist item or grant your end users access to edit mode. Editing rights include the ability to add, edit, and delete links in a checklist or specify link text for a particular link address. Additionally, you can configure checklist to open all links in the current window or in a new window.
Checklist editing
You can configure checklist to grant your end users access to edit mode. When this component is in the edit mode, the user can add, edit, delete, or reorder items in the checklist.
Loading spinner
You can configure a loading spinner to appear when the system is saving an end user’s changes to the checklist.
Design recommendations
Learn how to apply checklist in your design.
Use checklists when you want to do more than only indicate status of checklist items.
Avoid using checklists for only one item.
Alignment and positioning
You can place checklists in forms, lists, or side panels in an experience. Where you place the checklist determines how it aligns with the surrounding context. The checklist follows the guidelines of any adjacent, larger page element or structure (such as a list or side panel).
For left-to-right (LTR) languages, always place the prefix to the left of the checkbox.
UI text guidelines
These are some recommendations for using text within checklist.
Checklist labels
- Keep labels concise; refrain from using more than one sentence.
- Labels should be clear and unambiguous.
- Use sentence case for your checklist labels.
- Don't add a period to the end of a checkbox label; the exception to this is when a checkbox label is more than one sentence long.
- Start the label with a positive action that describes the selected state, such as "Close windows after quitting an application."
- Avoid using a negative action in the label, such as, "Don't send me email notifications"; this would mean that a user would have to select the option to turn off the setting.
Checklist text links
- Keep labels short.
- Don't write a generic or non-descriptive label (such as "click here" or "link"); the label should describe where the user goes when they select the link.
- Use consistent capitalization for all text links in your design.
- Only use symbols in a text link when they're necessary for understanding a word or phrase.
- Don't include a period in a text link.
Behavior
Learn how checklist behaves when the user interacts with the component.
States
Checklist has the following states: default, error, loading, and empty
Default
Checklist is in the default state when no one is interacting with it.
Shows the checklist in editing and non-editing mode when the user is not interacting with it.
Error
Checklist enters the error state when the user selects the “Apply” action (for Link) or the “Save” action, and required fields are left empty. The form field error message disappears as soon as something is added to the empty field.
You can configure the contents of the form validation message that appears when a required field is in the error state.
In the example on the left, the user is attempting to save a checklist item in edit mode with a required field left empty. The example on the right shows the error message displayed when the user attempts to apply changes to the link in edit mode with a required field left empty.
Loading
Checklist enters the loading state when loading data from the database or when the user selects the “Save” action to save their changes. If configured, the loader spinner appears to indicate that the checklist is loading new data.
The loader icon spins when checklist is saving changes, indicating the loading state.
Empty
The empty state messages are dependent on the mode of the checklist and if the checklist is empty.
An error message advises users when no checkbox items are added for a non-editable list.
If an editable checklist doesn’t have any checkbox items, the error message includes the “Add item” action, allowing the user to add checkbox items.
If all checkbox items have been deleted in an editable checklist, the user has several available actions. The user can select the “Add item” action to add checklist items. Selecting “Save” displays the previous empty state message with the “Add item” action. Selecting “Cancel” cancels any changes and displays the previously saved state.
Responsive behavior
If the checkbox label or link is longer than the container, it wraps to the next line. When the link text wraps to a new line, the action icons move to align on the right.
In the example on the left, the link actions align to the link text when the link appears on a single line. When the link text wraps to a second line, as in the second example, the link actions align to the right.
Interactions
Learn about the ways that the user can interact with the component.
Selecting checkboxes
The user can select or unselect checkboxes by selecting the checkbox container or label.
Edit mode
If configured, the user can select “Edit” to put the checklist into edit mode. This enables the user to edit, add, or delete checkbox items or link content. Users can also reorder a checklist when in edit mode by dragging and dropping items.
Editing a checklist item and link
When in edit mode, the user can edit the checkbox entry by putting the cursor in the text box. To edit the link and link text, the user selects the pencil icon next to the link. The user then makes the changes to the link or link text in the input fields that appear and selects “Apply.” To save the changes, the user selects “Save.”
In the example on the left, the user selects the checkbox text and places the cursor inside the text box to edit the content. To edit the link text or the URL, the user selects the pencil icon. The example on the right shows the input fields that appear for editing the link and its target.
Adding a checklist item and link
Users can add items to the checklist or add links. To add an item, the user selects “Add item.” A checkbox text input appears, allowing the user to create the content for the new item.
The user has the option to add a link to the new checklist item. When the user selects “Add link”, two additional input fields appear below the associated checkbox input text. One field is for the text that appears in the link and the other field for the actual URL. The user selects “Apply” to add the new link and link text to the checkbox item. The user selects “Save” to save the new checkbox and link to the checklist.
Removing a checklist item and link
To remove a checklist item, the user selects the trash icon next to the checkbox text input. To remove a link, the user selects the remove action next to the link text.
Reordering a checklist item
The user can reorder items in a checklist by dragging the checkbox by its drag handle and dropping it into a new location. As the user drags the checkbox item, an indicator appears to help the user position the item in its new location.
Truncation
Checkbox labels and links don’t truncate; they wrap to the next line.
Usability
Checklist complies with all internationalization and accessibility requirements.
Internationalization
When this component is used in a platform configured for a right-to-left (RTL) language, the checkbox moves to the right of the label and aligns with the right side of the container. If a prefix is used, the checkbox aligns to the left side of the prefix.
The image on the right shows the alignment when the checklist is in the edit mode. All elements are flipped to flow from right to left.
Accessibility
Learn how to access the actionable elements of checklist through keyboard interactions and screen readers.
Checklist tab order
You can access the actionable elements of checklist with these keyboard keys.
The example on the left shows the tab order for a static checklist. The image on the right shows the tab order for a checklist in edit mode.
Keyboard interactions
Static mode focus
| #1 - With focus on checkbox |  |
|---|---|
| Tab | Moves focus to the next interactive element |
| Space | Selects or deselects a checkbox |
| #2 - With focus on link |  |
|---|---|
| Tab | Moves focus to the next interactive element |
| Enter | Launches the link and moves focus to the link target |
| #3 - With focus on Edit action |  |
|---|---|
| Tab | Moves focus to the next interactive element |
| Space or Enter | Activates the button and places focus on the first interactive element; if activating the button does not dismiss the current context, then focus remains on the button after activation |
Edit mode focus
| #4 - With focus on text boxes (input) |  |
|---|---|
| Tab | Moves focus to the next interactive element |
| Enter | Does not perform an action |
Reordering focus
| #1 - With focus on the drag handle |  |
|---|---|
| Space or Enter | Toggles reorder mode to ON and keeps focus on the selected element |
| #2 - With focus on the drag handle in a pressed state |  |
|---|---|
| Arrow up or Arrow down | Moves position of the selected item up or down, marked with an indicator line |
| Space or Enter | Completes the action, toggles reorder mode to OFF, and keeps focus on the selected element |
| Esc | Exits reorder mode and keeps focus on the selected element; also discards any changes |
| Tab | Exits reorder mode, discards any changes, and moves focus to the next interactive element |
Screen readers
Screen readers announce the controls and content of checklist in the prescribed tab order. Screen readers identify the name and role of each element in the checklist.