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?

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

Choose one of the following list styles. 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. The following is an example of a numbered list: Here's a sequence of steps to follow: Open the box. Remove the bobcat from the box. Feed the bobcat. Nested sequential lists are labeled with lowercase letters or lowercase Roman numerals. The following is an example of a nested sequential list: Here's a list of things to do after breakfast, in order: Go shopping. Buy groceries: Flour Eggs Sugar Butter Go to mall: Buy dress. Buy shoes. Make cake. Build birthday present out of spare parts. Clean house. See also Sub-steps in numbered procedures.	ol, li
Bulleted list	A set of items that's neither a sequence nor options. The following is an example of a bulleted list: 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). The following is an example of a description list: 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 introductory terms or phrases, each followed by a description, definition, or explanation. Use this type of list if you want to highlight and explain several concepts or save space. For information about how to format and punctuate run-in headings and their descriptions, see Description lists that use run-in headings in this document. The following is an example of a description list that uses bulleted run-in headings: 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 the br element are legitimate and which aren't.)

Example of a list item that contains 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

Introduce a list with the appropriate context. In most cases, 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.

If the list doesn't need any additional context other than the heading that immediately precedes the list, it's OK to not introduce a list with an introductory sentence.

Introduce a list with a complete sentence, not a partial one that's completed by the list items. You can also use the following as a noun phrase (see following in the word list).

Recommended	Not 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.	Use the Submit button to: Submit the form. Indicate that you're done. Allow the next person to enter their data.
To get the USB driver, follow these steps: Click Tools > Android > SDK Manager. Select Google USB Driver, and then click OK.	To get the USB driver: Click Tools > Android > SDK Manager. Select Google USB Driver, and then click OK.
If you need to add an instance manually, do the following: Click Create instance. For Name, enter a name.	If you need to add an instance manually: Click Create instance. For Name, enter a name.
Objectives Create an instance Snapshot an instance Delete an instance	Objectives In the following tutorial, you will complete the following tasks: Create an instance Snapshot an instance Delete an instance

For information about introducing sub-steps, see Sub-steps in numbered procedures.

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

Unusual list numbering

Use nonstandard numbering in the following situations:

• To present a list in reverse-numerical order, use an ol element with a reversed attribute.
• To set a value manually, use the value attribute. In some cases, setting a value manually can be convenient. 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

Start each list item with a capital letter, unless case is an important part of the information conveyed by the list—such as in a list of glossary terms.

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.
• If the item is entirely link text or a document title, don't add end punctuation.

Note: These exceptions apply to individual list items, so it's possible to end up with a list that includes some items that end with periods and some that don't. To avoid this, use parallel construction for the items so that either all of the items end with periods or none of them do.

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.

Recommended	Not recommended
The following words are adjectives: Big A short word. Relevant A fancy word. Gratuitous A long word. Purple A vibrant color.	The following words are adjectives: Big Relevant Gratuitous Purple—this is a color.

Description lists that use run-in headings

In most contexts, format run-in headings as follows:

• Start the run-in heading with a capital letter.
• End the run-in heading with a period or a colon, but be consistent within the list.
• You can decide whether to bold the punctuation that ends the heading based on factors such as on-page consistency.

For the descriptions that follow the punctuation, capitalize the first letter as follows:

• If the text follows a period, start the text with a capital letter.
• If the text follows a colon, start the text with a lowercase letter.

To end the descriptive text, punctuate as follows:

• If the description follows a period, end the description with a period.
• If the description follows a colon, do one of the following:
• If the description is a list of items or short phrases without verbs, don't include a period.
• If the description includes a verb or expresses a standalone thought, end the description with 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....

Note: The guidelines here about list punctuation differ from the Material Design guidelines. If you're writing UI text rather than prose documentation, then follow the Material Design guidelines.