This is a snapshot of an early working draft and has therefore been superseded by the HTML standard.

This document will not be further updated.

HTML 5

Call For Comments — 27 October 2007

3.11. Lists

3.11.1. The ol element

Block-level element, and structured inline-level element.

Contexts in which this element may be used:
Where block-level elements are expected.
Where structured inline-level elements are allowed.
Content model:
Zero or more li elements.
Element-specific attributes:
start
DOM interface:
interface HTMLOListElement : HTMLElement {
           attribute long start;
};

The ol element represents an ordered list of items (which are represented by li elements).

The start attribute, if present, must be a valid integer giving the ordinal value of the first list item.

If the start attribute is present, user agents must parse it as an integer, in order to determine the attribute's value. The default value, used if the attribute is missing or if the value cannot be converted to a number according to the referenced algorithm, is 1.

The items of the list are the li element child nodes of the ol element, in tree order.

The first item in the list has the ordinal value given by the ol element's start attribute, unless that li element has a value attribute with a value that can be successfully parsed, in which case it has the ordinal value given by that value attribute.

Each subsequent item in the list has the ordinal value given by its value attribute, if it has one, or, if it doesn't, the ordinal value of the previous item, plus one.

The start DOM attribute must reflect the value of the start content attribute.

3.11.2. The ul element

Block-level element, and structured inline-level element.

Contexts in which this element may be used:
Where block-level elements are expected.
Where structured inline-level elements are allowed.
Content model:
Zero or more li elements.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The ul element represents an unordered list of items (which are represented by li elements).

The items of the list are the li element child nodes of the ul element.

3.11.3. The li element

Contexts in which this element may be used:
Inside ol elements.
Inside ul elements.
Inside menu elements.
Content model:
When the element is a child of an ol or ul element and the grandchild of an element that is being used as an inline-level content container, or, when the element is a child of a menu element: inline-level content.
Otherwise: zero or more block-level elements, or inline-level content (but not both).
Element-specific attributes:
If the element is a child of an ol element: value
If the element is not the child of an ol element: None.
DOM interface:
interface HTMLLIElement : HTMLElement {
           attribute long value;
};

The li element represents a list item. If its parent element is an ol, ul, or menu element, then the element is an item of the parent element's list, as defined for those elements. Otherwise, the list item has no defined list-related relationship to any other li element.

When the list item is the child of an ol or ul element, the content model of the item depends on the way that parent element was used. If it was used as structured inline content (i.e. if that element's parent was used as an inline-level content container), then the li element must only contain inline-level content. Otherwise, the element may be used either for inline content or block-level elements.

When the list item is the child of a menu element, the li element must contain only inline-level content.

When the list item is not the child of an ol, ul, or menu element, e.g. because it is an orphaned node not in the document, it may contain either for inline content or block-level elements.

When used as an inline-level content container, the list item represents a single paragraph.

The value attribute, if present, must be a valid integer giving the ordinal value of the first list item.

If the value attribute is present, user agents must parse it as an integer, in order to determine the attribute's value. If the attribute's value cannot be converted to a number, it must be treated as if the attribute was absent. The attribute has no default value.

The value attribute is processed relative to the element's parent ol element (q.v.), if there is one. If there is not, the attribute has no effect.

The value DOM attribute must reflect the value of the value content attribute.

3.11.4. The dl element

Block-level element, and structured inline-level element.

Contexts in which this element may be used:
Where block-level elements are expected.
Where structured inline-level elements are allowed.
Content model:
Zero or more groups each consisting of one or more dt elements followed by one or mode dd elements.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The dl element introduces an unordered association list consisting of zero or more name-value groups (a description list). Each group must consist of one or more names (dt elements) followed by one or more values (dd elements).

Name-value groups may be terms and definitions, metadata topics and values, or any other groups of name-value data.

The following are all conforming HTML fragments.

In the following example, one entry ("Authors") is linked to two values ("John" and "Luke").

<dl>
 <dt> Authors
 <dd> John
 <dd> Luke
 <dt> Editor
 <dd> Frank
</dl>

In the following example, one definition is linked to two terms.

<dl>
 <dt lang="en-US"> <dfn>color</dfn> </dt>
 <dt lang="en-GB"> <dfn>colour</dfn> </dt>
 <dd> A sensation which (in humans) derives from the ability of
 the fine structure of the eye to distinguish three differently
 filtered analyses of a view. </dd>
</dl>

The following example illustrates the use of the dl element to mark up metadata of sorts. At the end of the example, one group has two metadata labels ("Authors" and "Editors") and two values ("Robert Rothman" and "Daniel Jackson").

<dl>
 <dt> Last modified time </dt>
 <dd> 2004-12-23T23:33Z </dd>
 <dt> Recommended update interval </dt>
 <dd> 60s </dd>
 <dt> Authors </dt>
 <dt> Editors </dt>
 <dd> Robert Rothman </dd>
 <dd> Daniel Jackson </dd>
</dl>

If a dl element is empty, it contains no groups.

If a dl element contains non-whitespace text nodes, or elements other than dt and dd, then those elements or text nodes do not form part of any groups in that dl, and the document is non-conforming.

If a dl element contains only dt elements, then it consists of one group with names but no values, and the document is non-conforming.

If a dl element contains only dd elements, then it consists of one group with values but no names, and the document is non-conforming.

The dl element is inappropriate for marking up dialogue, since dialogue is ordered (each speaker/line pair comes after the next). For an example of how to mark up dialogue, see the dialog element.

3.11.5. The dt element

Contexts in which this element may be used:
Before dd or dt elements inside dl elements.
Before a dd element inside a dialog element.
Content model:
Strictly inline-level content.
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The dt element represents the term, or name, part of a term-description group in a description list (dl element), and the talker, or speaker, part of a talker-discourse pair in a conversation (dialog element).

The dt element itself, when used in a dl element, does not indicate that its contents are a term being defined, but this can be indicated using the dfn element.

3.11.6. The dd element

Contexts in which this element may be used:
After dt or dd elements inside dl elements.
After a dt element inside a dialog element.
Content model:
When the element is a child of a dl element and the grandchild of an element that is being used as an inline-level content container: inline-level content.
Otherwise: zero or more block-level elements, or inline-level content (but not both).
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The dd element represents the description, definition, or value, part of a term-description group in a description list (dl element), and the discourse, or quote, part in a conversation (dialog element).

The content model of a dd element depends on the way its parent element is being used. If the parent element is a dl element that is being used as structured inline content (i.e. if the dl element's parent element is being used as an inline-level content container), then the dd element must only contain inline-level content.

Otherwise, the element may be used either for inline content or block-level elements.