Lists

Group related content items together either vertically or horizontally

# Overview

# Bare

Collect items to be displayed in a list when items are not marked with bullets. This is the default and is also known as unordered and undecorated “bare” list.

# Unordered

Collect related items that don’t need to be in a specific order or sequence. List items are typically marked with bullets.

# Ordered

Collect related items with numeric order or sequence. Numbering starts at 1 with the first list item and increases by increments of 1 for each successive ordered list item.

# Compact

Compact modifier can be added to any cdr-list in order to reduce the margin between list items.

# Inline

Display items horizontally with no divider.

# Inline - Unordered

Display items horizontally, separated by a bullet character.

# Accessibility

To ensure that usage of this component complies with accessibility guidelines:

  • Organize lists so users can understand the relationship and grouping of information
  • Use explicit list markup that allows users to:
    • Rapidly browse
    • Navigate a page using list content
    • Announce the number of items in each list when using screen readers

When creating nested lists, ensure they are coded properly. Always check that:

  • List items are contained within one list
  • Spacing does not break a list into multiple individual points
  • Proper semantic tags are used - either <ol> or <ul>
  • Proper structure is used to provide a visual list, do not rely on indentation
  • Special characters are not used to create a list

This component has compliance with WCAG guidelines by:

  • Providing ability to create structured lists. Lists are easier to navigate than simple tables

# Guidelines

# Use When

  • Displaying groups of related items represented by text

# Don't Use When

  • Displaying content that is not primarily text
  • Displaying content with two or more well-defined dimensions. Instead, use Data Tables

# The Basics

  • Lists can inherit cdr-text modifiers to make any text a list
  • Follow spacing requirements found on Typography and Spacing pages

# Content

Break up chunks of content to make the information easier to scan:

  • Separate consecutive lists on a page with a heading for each list
  • Start each item with a noun or a verb
  • Use similar phrases or clauses with the same grammatical structure. For example:
    • Product. Zippered hand pockets; chest pocket with hidden zipper
    • Materials. Snowshoes: plastic; poles: aluminum
    • Duration. High: 4 hrs. 15 min.; low: 48 hrs. 20 min.
  • Create structured content with a list. Do not use a list for formatting

Use multi-column lists when:

  • Specific ordering is not required
  • Listing items with a single word or very short phrases
  • Space is minimal
  • Viewing items at a glance is more beneficial than scrolling

Every item in a list must:

  • Start with a capital letter and use sentence case
  • Use semicolons when linking independent clauses and product details in the list
  • End each sentence in a list item with a period when there are multiple sentences; however, don’t add a period for the last sentence or phrase

# Do / Don’t

Do link independent clauses and product details.
Don't link unrelated items together.

Do end each sentence with a period except last sentence.
Don't add terminal punctuation.

# Resources

WebAIM: Semantic Structure: Using Lists Correctly


# API

# Props

This component will bind any attribute that a native HTML list element accepts.

tag

name

string

type

'ul'

default

Sets valid HTML element tag. Possible values: { ‘ul’ | ‘ol’ }

modifier

name

string

type

N/A

default

Modifies the style variant for this component. Possible values: { ‘ordered’ | ‘unordered’ | ‘compact’ | ‘inline’ }

# Slots

Find more information about using Slots in the article Getting Started as a Developer.

default

name

Sets the innerHTML for CdrList. This includes text and html markup.

# Usage

Visual style and semantic meaning are managed independently by providing:

  • Element to the tag prop
  • Style to the modifier prop

By default the CdrList component renders as an unordered and undecorated "bare" list. To use an ordered list, pass <ol> to the tag property.

<cdr-list tag="ol">
  <li> item one </li>
  <li> item two </li>
</cdr-list>
1
2
3
4

The CdrList component has decoupled the semantic tags <ul> and <ol> from visual presentation.


It is possible to render a semantic ordered list <ol> as a visually non-styled or bulleted list using the cdr-list modifiers. With this decoupling, individual list items can contain a variety of HTML elements, including paragraphs, headings, form elements, and other (nested) lists. Ensure that content is structured and follows design guidelines.

# Tag Variants

Following are different types of lists:

  • Unordered lists:
    • Used when the order of the items is not relevant
    • Consists of one <ul> element and multiple list item <li> elements
  • Ordered lists:
    • Used for sequential information
    • Consists of one <ol> element and multiple list item <li> elements
  • Nested lists:
    • Every cdr-list can be nested into another list
    • Assistive technology can easily inform users about the number of steps
<cdr-list>
   <li> Unordered list item text
     <cdr-list tag="ol">
       <li>Ordered list item text</li>
     </cdr-list>
   </li>
 </cdr-list>
1
2
3
4
5
6
7
  • Bare or unstyled lists:
    • Contains a variety of HTML elements, including paragraphs, headings, form elements, and other (nested) lists

# Modifiers

Note that the tag itself does not determine display, a modifier must be added for list styles. Add one of the following variants to the modifier attribute of the cdr-list tag to change the visual presentation:

Value Description
'unordered' List items are typically marked with bullets
'ordered' List items are typically marked with numbers
'compact' Reduces spacing between list items
'inline' List items appear horizontally with no divider