Skip to content
lib components / Text

List

Use this component to vertically group related text-only items. Use an ordered list to communicate a specific priority, hierarchy, or sequence. Use an unordered list when the order of the items is not important.

ExamplesPropertiesGuidelines
import { Ul, Ol } from "@siteimprove/fancylib";

#Examples

The main difference between the two components is that the items in the ordered list component feature numbers, while the items in the unordered list feature bullets.

#Default unordered list

Here you can see an example of the default appearance of an unordered list.

  • Darth Vader
  • Luke Skywalker
  • Princess Leia
<Ul items={["Darth Vader", "Luke Skywalker", "Princess Leia"]} />

#Default ordered list

Here you can see an example of the default appearance of an ordered list.

  1. Star Wars: Episode IV – A New Hope (1977)
  2. Star Wars: Episode V – The Empire Strikes Back (1980)
  3. Star Wars: Episode VI – Return of the Jedi (1983)
<Ol items={[ "Star Wars: Episode IV – A New Hope (1977)", "Star Wars: Episode V – The Empire Strikes Back (1980)", "Star Wars: Episode VI – Return of the Jedi (1983)", ]} />

#Nested lists

List components can be nested inside each other, as you can see in the example below. Nested lists do not have to be of the same type as the parent list.

  1. Original trilogy
    1. Star Wars: Episode IV – A New Hope (1977)
    2. Star Wars: Episode V – The Empire Strikes Back (1980)
    3. Star Wars: Episode VI – Return of the Jedi (1983)
  2. Prequel trilogy
    1. Star Wars: Episode I – The Phantom Menace (1999)
    2. Star Wars: Episode II – Attack of the Clones (2002)
    3. Star Wars: Episode III – Revenge of the Sith (2005)
  3. Sequel trilogy
    1. Star Wars: Episode VII – The Force Awakens (2015)
    2. Star Wars: Episode VIII – The Last Jedi (2017)
    3. Star Wars: Episode IX – The Rise of Skywalker (2019)
<Ol items={[ <> Original trilogy <Ol items={[ "Star Wars: Episode IV – A New Hope (1977)", "Star Wars: Episode V – The Empire Strikes Back (1980)", "Star Wars: Episode VI – Return of the Jedi (1983)", ]} /> </>, <> Prequel trilogy <Ol items={[ "Star Wars: Episode I – The Phantom Menace (1999)", "Star Wars: Episode II – Attack of the Clones (2002)", "Star Wars: Episode III – Revenge of the Sith (2005)", ]} /> </>, <> Sequel trilogy <Ol items={[ "Star Wars: Episode VII – The Force Awakens (2015)", "Star Wars: Episode VIII – The Last Jedi (2017)", "Star Wars: Episode IX – The Rise of Skywalker (2019)", ]} /> </>, ]} />

#Properties

#Unordered list

  • Darth Vader
  • Luke Skywalker
  • Princess Leia
PropertyDescriptionDefinedValue
itemsRequired
element[]Items displayed in the list
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Ordered list

  1. Star Wars: A New Hope (1977)
  2. Star Wars: The Empire Strikes Back (1980)
  3. Star Wars: Return of the Jedi (1983)
PropertyDescriptionDefinedValue
itemsRequired
element[]Items displayed in the list
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Guidelines

#Best practices

  • Use a list when you need to group related items that only consist of text.
  • Use for three or more items
  • Use an ordered list when you need to communicate a specific priority, hierarchy, or sequence.
  • Use an unordered list when the order of the items is not important.
  • List items in unordered lists in a logical manner (e.g. alphabetically), to make it easy to find items.
  • Do not nest lists more than two levels deep. Break them up into separate lists instead.

#Do not use when

The items consist of complex data with multiple dimensions. Use a table or list table instead.

#Accessibility

Keep list items as short as possible and limited to 1 or 2 pieces of information.

The component’s implementation ensures that it automatically follows these guidelines:

  • Use proper semantic markup, meaning: wrap li elements in either a ul or ol element.
  • Add role=“list” to ul and ol elements.
  • An aria-label is not required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Use an unordered list to present key ideas in place of a longer paragraph.
  • Keep list items short, snappy, and limited to a single sentence. If that’s not possible, consider using paragraphs with headings instead. As you can see, this rule does not apply to this styleguide.
  • Make sure list items are self-contained, but thematically similar, ideas. So, for instance, don't string list items together by using “or” or “and” at the end of an item.
  • Don’t end list items with punctuation — no full stops, no semicolons. This is another rule that does not apply to this styleguide.
  • Don’t mix and match sentence structures. So, for instance, start each list item with a verb or a noun, and stick to that formula all the way through.
  • Use a lead-in sentence when you need to give context to the list items. A lead-in is a partial sentence that is completed by the list items (e.g. “Web Security allows you to:”).
  • If you’re using a lead-in sentence, make sure every list item makes sense when placed next to it (e.g. “Web security allows you to: protect your users and your reputation”).
  • Use uppercase for the first word of a list item, unless it’s a continuation of a lead-in sentence.