Lists

List or table?

Tables and lists are both ways to present a set of similarly structured items. Sometimes it's not obvious when to choose one presentation over the other. To decide which presentation to use, see List or table? on the page about tables.

Note: Don't use a list to show only one item; a single item isn't really a list. If you want to set a single item off from surrounding text, then use some other formatting.

Types of lists

The following table includes common ways to present lists in our documentation.

List type Used for HTML elements
Numbered list A sequence of steps to be performed in order. For example:

Here's a sequence of steps to follow:

  1. Open the box.
  2. Remove the bobcat from the box.
  3. Feed the bobcat.

Note that nested sequential lists are labeled with lowercase letters or lowercase Roman numerals. For example:

Here's a list of things to do after breakfast, in order:

  1. Go shopping.
    1. Buy groceries:
      • Flour
      • Eggs
      • Sugar
      • Butter
    2. Go to mall:
      1. Buy dress.
      2. Buy shoes.
  2. Make cake.
  3. Build birthday present out of spare parts.
  4. Clean house.

See also Sub-steps in numbered procedures.

ol, li
Lettered list (upper case) Options to choose among, especially mutually exclusive options. For example:

Here's a set of options for which programming language to use:

  1. Java
  2. JavaScript
  3. Go
  4. Dart
ol class="upper-alpha", li
Bulleted list A set of items that's neither a sequence nor options. For example:

Here's a list of things that can go wrong, in no particular order:

  • Your bicycle might explode.
  • The sun might go out.
  • An ant might break its leg and require a tiny splint.
ul, li
Description list A set of terms, each with a description, definition, or explanation. Use this type of list if you want to draw attention to two or more terms (such as a glossary). For example:

Here are some descriptions of types of birds:

Emu
The best kind of bird.
Crow
The other best kind of bird.
Peacock
Also the best kind of bird.
Phoenix
An even better kind of bird.
dl, dt, dd
Description list that uses bulleted run-in headings A set of terms or phrases, each with a description, definition, or explanation. Use this type of list if you want to highlight and explain several concepts and/or save space. Use bold formatting for the introductory text and punctuation. For example:

Here are some descriptions of types of birds:

  • Emu. The best kind of bird.
  • Crow. The other best kind of bird.
  • Peacock. Also the best kind of bird.
  • Phoenix. An even better kind of bird.
ul, li

Multiple paragraph list items

Any list item can contain more than one paragraph.

To create multiple paragraphs, use the <p> element rather than using the <br> element. (The HTML specification describes which uses of <br> are legitimate and which aren't.)

Example of a list item containing more than one paragraph:

  • This list item is a single paragraph.
  • This list item contains multiple paragraphs.

    As you can see!

  • This is another list item that's only one paragraph long.

Introductory sentences for lists

In most cases, you should precede a list with an introductory sentence. The sentence can end with a colon or a period; usually a colon if it immediately precedes the list, usually a period if there's more material (such as a note paragraph) between the introduction and the list.

Always introduce a list with a complete sentence, not a partial one that's completed by the list items.

For information about punctuation and capitalization of lists, see Capitalization and end punctuation.

Not recommended:

Use the Submit button to:

  • Submit the form.
  • Indicate that you're done.
  • Allow the next person to enter their data.

Recommended:

Use the Submit button for any of the following purposes:

  • To submit the form.
  • To indicate that you're done.
  • To allow the next person to enter their data.

Not recommended:

To get the USB driver:

  1. Click Tools > Android > SDK Manager.
  2. Select Google USB Driver, and then click OK.

Recommended:

To get the USB driver, follow these steps:

  1. Click Tools > Android > SDK Manager.
  2. Select Google USB Driver, and then click OK.

Unusual list numbering

Use nonstandard numbering in the following situations:

  • To present a list in reverse-numerical order, use <ol reversed>.
  • To set a value manually, use the value attribute. In some cases, setting a value by hand can come in handy. However, in most cases, it isn't a good idea to manually number a list item in a numbered list, because if the number of items changes later, you'll have to manually change the value.

Sub-steps in a numbered procedure

For information about sub-steps in a numbered procedure, see Procedures.

Parallel syntax

Use the same syntax/structure for all list items in a given list, if possible.

Capitalization and end punctuation

Capitalization and end punctuation depend on the type of list and the contents of the list.

Numbered, lettered, and bulleted lists

In most contexts, start each list item with a capital letter.

End each list item with a period or other appropriate sentence-ending punctuation, except in the following cases:

  • If the item consists of a single word, don't add end punctuation.
  • If the item doesn't include a verb, don't add end punctuation.
  • If the item is entirely in code font, don't add end punctuation.

Recommended:

The following words are adjectives:

  • Big
  • Small
  • Gratuitous

Recommended:

The SDK supports the following UI elements:

  • Text box
  • Bulleted list
  • Button

Recommended:

The API supports the following actions:

  • Create
  • Replace
  • Update
  • Delete

Recommended:

You can do any of the following by using the API:

  • Create an item.
  • Replace one item with another.
  • Update an item.
  • Delete an item.

Description lists

Sometimes it's useful to add an explanatory phrase to a list item, which can affect the punctuation. In general, don't add an explanatory phrase to only a single list item; instead, use a description list, and provide explanatory phrases for all items.

In most contexts, start each term (<dt> element) with a capital letter.

Don't end the term with a period. Do generally put a period at the end of each dd ("description") element.

Not recommended:

The following words are adjectives:

  • Big
  • Relevant
  • Gratuitous
  • Purple—this is a color.

Recommended:

The following words are adjectives:

Big
A short word.
Relevant
A fancy word.
Gratuitous
A long word.
Purple
A vibrant color.

Description lists that use run-in headings

In most contexts, start each term or phrase with a capital letter. For the descriptions, start text that follows periods with a capital letter, and text that follows colons with a lowercase letter.

End the introductory term or phrase with a period or colon. If a description follows a period, end the description with a period. If it follows a colon, use your judgment; for example, if it's a list of items or short phrases without verbs, don't include a period.

Don't use a dash to set off a description from an item in a description list. For more information, see Colons instead of dashes in lists.

Recommended:

The following words are adjectives:

  • Big: a short word
  • Relevant: a fancy word
  • Gratuitous: a long word
  • Purple: a vibrant color

Recommended:

The coffee shop has several great choices:

  • Coffee: latte, mocha, cappuccino, espresso, macchiato
  • Tea: chai tea, chai latte, black tea, green tea, herbal tea

Recommended:

Budget Airlines reduces your ticket cost in several ways:

  • It increases fuel economy by reducing baggage weight. By charging astronomical prices for anything larger than a wallet....
  • It carries more passengers per flight. By reducing leg room to industry and medical minimums, it fits more seats....