4.4. Grouping content
4.4.1. The p
element
- Categories:
- Flow content.
- Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Phrasing content.
- Tag omission in text/html:
- A
p
element’s end tag may be omitted if thep
element is immediately followed by anaddress
,article
,aside
,blockquote
,details
,div
,dl
,fieldset
,figcaption
,figure
,footer
,form
,h1
,h2
,h3
,h4
,h5
,h6
,header
,hr
,main
,nav
,ol
,p
,pre
,section
,table
, orul
, element, or if there is no more content in the parent element and the parent element is an HTML element that is not ana
,audio
,del
,ins
,map
,noscript
, orvideo
element. - Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
- Any role value.
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLParagraphElement
: HTMLElement {};
The p
element represents a block of content, a paragraph as defined in this specification.
The p
element should not be used when a more specific element, such as a list, is more appropriate.
p
elements.
When the parser finds them, it automatically closes the p
element - effectively inserting a </p>
tag.
These elements are: heading content, most sectioning roots and sectioning content, form
, fieldset
, table
, ol
, ul
, and legend
. Paragraphs are usually represented visually as blocks of text, separated from adjacent blocks by blank lines. However a style sheet or user agent may present paragraph breaks in a different manner, for instance using inline pilcrows (¶).
<p>The little kitten gently seated itself on a piece of carpet. Later in his life, this would be referred to as the time the cat sat on the mat.</p>
<p>There was once an example from Femley,<br> Whose markup was of dubious quality.<br> The validator complained,<br> So the author was pained,<br> To move the error from the markup to the rhyming.</p>;
<section> <!-- ... --> <p>Last modified: 2001-04-23</p> <p>Author: fred@example.com</p> </section>
However, it would be better marked-up as:
<section> <!-- ... --> <footer>Last modified: 2001-04-23</footer> <address>Author: fred@example.com</address> </section>
Or:
<section> <!-- ... --> <footer> <p>Last modified: 2001-04-23</p> <address>Author: fred@example.com</address> </footer> </section>
li
, ol
, and ul
) cannot be children of p
elements.
So to mark up a sentence that contains a list, like the following:
-
wizards,
-
faster-than-light travel, and
-
telepathy,
and is further discussed below.
it is important to remember that a paragraph in HTML does not have the semantic meaning of "a single idea" that is a usual part of how English grammar describes "paragraphs". Instead it is merely a default type of block-level structure for content. In the example above, there are five block-level structures: one before the list, one for each bullet, and one after the list.
<p>For instance, this fantastic sentence has bullets relating to</p> <ul> <li>wizards,</li> <li>faster-than-light travel, and</li> <li>telepathy,</li> </ul> <p>and is further discussed below.</p>
Authors wishing to conveniently style such "logical" paragraphs consisting of multiple
"structural" paragraphs can use the div
element instead of, or as well as the p
element.
<div>For instance, this fantastic sentence has bullets relating to <ul> <li>wizards,</li> <li>faster-than-light travel, and</li> <li>telepathy,</li> </ul> and is further discussed below.</div>
or
<div> <p>For instance, this fantastic sentence has bullets relating to</p> <ul> <li>wizards,</li> <li>faster-than-light travel, and</li> <li>telepathy,</li> </ul> <p>and is further discussed below.</p> </div>
These examples still have five structural blocks, but now the author can style just the div
instead of having to consider each part of the example separately.
4.4.2. The address
element
- Categories:
- Flow content.
- Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Flow content, but with no heading
content descendants, no sectioning content descendants, and no
header
,footer
, oraddress
element descendants. - Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
- Any role value.
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the allowed roles. - DOM interface:
- Uses
HTMLElement
.
The address
element represents contact information for a person, people or organization.
It should include physical and/or digital location/contact information and a means of identifying
a person(s) or organization the information pertains to.
<address> <p>W3C on Twitter:</p> <p><a href="https://twitter.com/w3c">@w3c</a></p> </address>
Address, telephone and fax numbers for an organization:
<address><br>UNIVERSITY INTERSCHOLASTIC LEAGUE<br> 1701 Manor Road, Austin, TX 78722<br> Tel: (512) 471-5883 | Fax: (512) 471-5908 </address>
The address part of a form output:
... <label for="name">Name:</label> <input type="text" id="name"> <label for="hn">House number:</label> <input type="text" id="hn"> <label for="street">Street:</label> <input type="text" id="street"> ... <address> <p>Name: Hament Dhanji</p> <p>House number: 123</p> <p>Street: Example Road</p> ... </address>
Location of a cat
<address> Lola the cat is at Latitude: 51.47852 Longtitude: -0.1449519 </address>
The meaning and usage contexts of the address
element is broad. If developers wish
to provide more granular and specific semantics for the address
element, use of any of
the various semantic web metadata schemas is suggested.
For example, the postal address of a local business annotated using RDFa:
<div vocab="http://schema.org/" typeof="LocalBusiness"> <h1><span property="name">Beachwear & Giftware</span></h1> <span property="description"> A superb collection of fine gifts and clothing to accent your stay in Mexico Beach.</span><address property="address" typeof="PostalAddress"><span property="streetAddress">123 Example Street</span> <span property="addressLocality">Mexico Beach</span>, <span property="addressRegion">FL</span></address>Phone: <span property="telephone">(212) 664-7665</span> </div>
4.4.3. The hr
element
- Categories:
- Flow content.
- Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Nothing.
- Tag omission in text/html:
- No end tag.
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
separator
(default - do not set),none
orpresentation
. - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLHRElement
: HTMLElement {}; - DPub Roles:
-
doc-pagebreak
The hr
element represents a paragraph-level thematic break, e.g., a
scene change in a story, or a transition to another topic within a section of a reference book.
hr
element to separate topics within the section.
<section> <h1>Communication</h1> <p>There are various methods of communication. This section covers a few of the important ones used by the project.</p> <hr> <p>Communication stones seem to come in pairs and have mysterious properties:</p> <ul> <li>They can transfer thoughts in two directions once activated if used alone.</li> <li>If used with another device, they can transfer one’s consciousness to another body.</li> <li>If both stones are used with another device, the consciousnesses switch bodies.</li> </ul> <hr> <p>Radios use the electromagnetic spectrum in the meter range and longer.</p> <hr> <p>Signal flares use the electromagnetic spectrum in the nanometer range.</p> </section> <section> <h1>Food</h1> <p>All food at the project is rationed:</p> <dl> <dt>Potatoes</dt> <dd>Two per day</dd> <dt>Soup</dt> <dd>One bowl per day</dd> </dl> <hr> <p>Cooking is done by the chefs on a set rotation.</p> </section>
There is no need for an hr
element between the sections themselves, since the section
elements and the h1
elements imply thematic changes
themselves.
hr
element.
<p>
Elizabeth told her the motives of her secrecy. She had been unwilling to mention Bingley; and the unsettled state of her own feelings had made her equally avoid the name of his friend. But now she would no longer conceal from her his share in Lydia’s marriage. All was acknowledged, and half the night spent in conversation.
</p>
<hr>
<p>
“Good gracious!” cried Mrs. Bennet, as she stood at a window the next morning, “if that disagreeable Mr. Darcy is not coming here again with our dear Bingley! What can he mean by being so tiresome as to be always coming here? I had no notion but he would go a-shooting, or something or other, and not disturb us with his company. What shall we do with him? Lizzy, you must walk out with him again, that he may not be in Bingley’s way.”
</p>
The hr
element does not affect the document’s outline.
4.4.4. The pre
element
- Categories:
- Flow content.
- Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Phrasing content.
- Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
- Any role value.
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLPreElement
: HTMLElement {};
The pre
element represents a block of preformatted text, in which structure is
represented by typographic conventions rather than by elements.
In the HTML syntax, a leading newline character immediately following the pre
element start tag is stripped.
Some examples of cases where the pre
element could be used:
-
Including an e-mail, with paragraphs indicated by blank lines, lists indicated by lines prefixed with a bullet, and so on.
-
Including fragments of computer code, with structure indicated according to the conventions of that language.
-
Displaying ASCII art.
Authors are encouraged to consider how preformatted text will be experienced when the formatting is lost, as will be the case for users of speech synthesizers, braille displays, and the like. For cases like ASCII art, it is likely that an alternative presentation, such as a textual description, would be more universally accessible to the readers of the document.
To represent a block of computer code, the pre
element can be used with a code
element; to represent a block of computer output the pre
element
can be used with a samp
element. Similarly, the kbd
element can be used
within a pre
element to indicate text that the user is to enter.
This element has rendering requirements involving the bidirectional algorithm.
<p>This is the <code>Panel</code> constructor:</p> <pre><code>function Panel(element, canClose, closeHandler) { this.element = element; this.canClose = canClose; this.closeHandler = function () { if (closeHandler) closeHandler() }; }</code></pre>
samp
and kbd
elements are mixed in the
contents of a pre
element to show a session of Zork I.
<pre><samp>You are in an open field west of a big white house with a boarded front door. There is a small mailbox here. ></samp> <kbd>open mailbox</kbd> <samp>Opening the mailbox reveals: A leaflet. ></samp></pre>
pre
element to preserve its
unusual formatting, which forms an intrinsic part of the poem itself.
<pre> maxling it is with a heart heavy that i admit loss of a feline so loved a friend lost to the unknown (night) ~cdr 11dec07</pre>
4.4.5. The blockquote
element
- Categories:
- Flow content.
- Sectioning root.
- Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Flow content.
- Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
cite
- Link to the source of the quotation.- Allowed ARIA role attribute values:
- Any role value.
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLQuoteElement
: HTMLElement { attribute DOMString cite; };The
HTMLQuoteElement
interface is also used by theq
element.
The blockquote
element represents content that is quoted from another source,
optionally with a citation which must be within a footer
or cite
element, and optionally with in-line changes such as annotations and abbreviations.
Content inside a blockquote
other than citations and in-line changes must be quoted
from another source, whose address, if it has one, may be cited in the cite
attribute.
In cases where a page contains contributions from multiple people, such as comments on a blog post, 'another source' can include text from the same page, written by another person.
If the cite
attribute is present, it must be a valid URL potentially surrounded by spaces. To obtain the corresponding citation link, the
value of the attribute must be parsed relative to the element’s node document.
User agents may allow users to follow such citation links, but they are primarily intended for
private use (e.g., by server-side scripts collecting statistics about a site’s use of quotations),
not for readers.
The cite
IDL attribute must reflect the element’s cite
content attribute.
The content of a blockquote
may be abbreviated, may have context added or may have
annotations. Any such additions or changes to quoted text must be indicated in the text (at the
text level). This may mean the use of notational conventions or explicit remarks, such as
"emphasis mine".
<blockquote> <p>[Fred] then said he liked [...] fish.</p> </blockquote>
Quotation marks may be used to delineate between quoted text and annotations within a blockquote
.
<figure> <blockquote> "That monster custom, who all sense doth eat Of habit’s devil," <abbr title="et cetera">&c.</abbr> not in Folio "What a falling off was there! From me, whose love was of that dignity That it went hand in hand even with the vow I made to her in marriage, and to decline Upon a wretch." </blockquote> <footer> — <cite class="title">Shakespeare manual</cite> by <cite class="author">Frederick Gard Fleay</cite>, p19 (in Google Books) </footer> </figure>
In the example above, the citation is contained within the footer
of a figure
element, this groups and associates the information, about the quote, with
the quote. The figcaption
element was not used, in this case, as a container for
the citation as it is not a caption.
Attribution for the quotation, may be be placed inside the blockquote
element, but
must be within a cite
element for in-text attributions or within a footer
element.
footer
after the quoted text, to
clearly relate the quote to its attribution:
<blockquote> <p>I contend that we are both atheists. I just believe in one fewer god than you do. When you understand why you dismiss all the other possible gods, you will understand why I dismiss yours.</p> <footer>— <cite>Stephen Roberts</cite></footer> </blockquote>
cite
element on the last line of the quoted
text. Note that a link to the author is also included.
<blockquote> The people recognize themselves in their commodities; they find their soul in their automobile, hi-fi set, split-level home, kitchen equipment. — <cite><a href="https://en.wikipedia.org/wiki/Herbert_Marcuse">Herbert Marcuse</a></cite> </blockquote>
footer
after the quoted text, and metadata about
the reference has been added using the RDFA Lite syntax. [rdfa-lite]
<blockquote> <p>... she said she would not sign any deposition containing the word "amorous" instead of "advances". For her the difference was of crucial significance, and one of the reasons she had separated from her husband was that he had never been amorous but had consistently made advances.</p> <footer typeof="schema:Book"> <span property="schema:author">Heinrich Böll</span>, <span property="schema:name">The Lost Honor of Katharina Blum</span>, <span property="schema:datePublished">January 1, 1974</span> </footer> </blockquote>
There is no formal method for indicating the markup in a blockquote
is from a
quoted source. It is suggested that if the footer
or cite
elements are
included and these elements are also being used within a blockquote
to identify
citations, the elements from the quoted source could be annotated with metadata to identify
their origin, for example by using the class
attribute (a defined
extensibility mechanism).
cite
element, which is annotated
using the class
attribute:
<blockquote> <p>My favorite book is <cite class="from-source">At Swim-Two-Birds</cite></p> <footer>- <cite>Mike[tm]Smith</cite></footer> </blockquote>
The other examples below show other ways of showing attribution.
blockquote
element is used in conjunction with a figure
element
and its figcaption
:
<figure> <blockquote> <p>The truth may be puzzling. It may take some work to grapple with. It may be counterintuitive. It may contradict deeply held prejudices. It may not be consonant with what we desperately want to be true. But our preferences do not determine what’s true.</p> <p>We have a method, and that method helps us to reach not absolute truth, only asymptotic approaches to the truth — never there, just closer and closer, always finding vast new oceans of undiscovered possibilities. Cleverly designed experiments are the key.</p> </blockquote> <figcaption> <cite>Carl Sagan</cite>, in "<cite>Wonder and Skepticism</cite>", from the <cite>Skeptical Inquirer</cite> Volume 19, Issue 1 (January-February 1995) </figcaption> </figure>
cite
alongside blockquote
:
<p>His next piece was the aptly named <cite>Sonnet 130</cite>:</p> <blockquote cite="https://quotes.example.org/s/sonnet130.html"> <p>My mistress' eyes are nothing like the sun,<br> Coral is far more red, than her lips red,<br> ...
blockquote
to show what post a user
is replying to. The article
element is used for each post, to mark up the
threading.
<article> <h1><a href="https://bacon.example.com/?blog=109431">Bacon on a crowbar</a></h1> <article> <header><strong>t3yw</strong> 12 points 1 hour ago</header> <p>I bet a narwhal would love that.</p> <footer><a href="?pid=29578">permalink</a></footer> <article> <header><strong>greg</strong> 8 points 1 hour ago</header> <blockquote> <p>I bet a narwhal would love that.</p> </blockquote> <p>Dude narwhals don’t eat bacon.</p> <footer><a href="?pid=29579">permalink</a></footer> <article> <header><strong>t3yw</strong> 15 points 1 hour ago</header> <blockquote> <blockquote> <p>I bet a narwhal would love that.</p> </blockquote> <p>Dude narwhals don’t eat bacon.</p> </blockquote> <p>Next thing you’ll be saying they don’t get capes and wizard hats either!</p> <footer><a href="?pid=29580">permalink</a></footer> <article> <header><strong>boing</strong> -5 points 1 hour ago</header> <p>narwhals are worse than ceiling cat</p> <footer><a href="?pid=29581">permalink</a></footer> </article> </article> </article> <article> <header><strong>fred</strong> 1 points 23 minutes ago</header> <blockquote> <p>I bet a narwhal would love that.</p> </blockquote> <p>I bet they’d love to peel a banana too.</p> <footer><a href="?pid=29582">permalink</a></footer> </article> </article> </article>
blockquote
for short snippets, demonstrating that
one does not have to use p
elements inside blockquote
elements:
<p>She began a list of quotations with the following:</p> <blockquote>It is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife.</blockquote> <p>She continued with a number of similar quotes, ending with:</p> <blockquote>The person, be it gentleman or lady, who has not pleasure in a good novel, must be intolerably stupid.</blockquote> <p>We shall now discuss these points...
Examples of how to represent a conversation are shown in a later section; it is not
appropriate to use the cite
and blockquote
elements for this purpose.
4.4.6. The ol
element
- Categories:
- Flow content.
- If the element’s children include at least one
li
element: Palpable content. - Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Zero or more
li
and script-supporting elements. - Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
reversed
- Number the list backwards.start
- Ordinal value of the first itemtype
- Kind of list marker.- Allowed ARIA role attribute values:
-
list
role (default - do not set),directory
,group
,listbox
,menu
,menubar
,none
,presentation
,radiogroup
,tablist
,toolbar
ortree
. - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLOListElement
: HTMLElement { attribute boolean reversed; attribute long start; attribute DOMString type; };
The ol
element represents a list of items, where the items have been
intentionally ordered, such that changing the order would change the meaning of the document.
The items of the list are the li
element child nodes of the ol
element,
in tree order.
The reversed
attribute is a boolean attribute. If present, it
indicates that the list is a descending list (..., 3, 2, 1). If the attribute is omitted, the list
is an ascending list (1, 2, 3, ...).
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 if
the element has no reversed
attribute, and is the number of child li
elements otherwise.
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 if the reversed
is absent, or minus one if it is present.
The type
attribute can be used to specify the kind of marker to use in the
list, in the cases where that matters (e.g., because items are to be referenced by their
number/letter). The attribute, if specified, must have a value that is a case-sensitive match for one of the characters given in the first cell of one of the rows of the following table.
The type
attribute represents the state given in the cell in the
second column of the row whose first cell matches the attribute’s value; if none of the cells
match, or if the attribute is omitted, then the attribute represents the decimal state.
User agents should render the items of the list in a manner consistent with the state of the type
attribute of the ol
element. Numbers less than or equal to zero
should always use the decimal system regardless of the type
attribute.
For CSS user agents, a mapping for this attribute to the list-style-type CSS property is given in the §10 Rendering section (the mapping is straightforward: the states above have the same names as their corresponding CSS values).
It is possible to redefine the default CSS list styles used to implement this attribute in CSS user agents; doing so will affect how list items are rendered.
The reversed
, start
, and type
IDL attributes must reflect the respective content
attributes of the same name. The start
IDL attribute has the same default as its
content attribute.
ol
element is therefore appropriate. Compare this list to the equivalent list in the ul
section to see an example of the same items using the ul
element.
<p>I have lived in the following countries (given in the order of when I first lived there):</p> <ol> <li>Switzerland</li> <li>United Kingdom</li> <li>United States</li> <li>Norway</li> </ol>
Note how changing the order of the list changes the meaning of the document. In the following example, changing the relative order of the first two items has changed the birthplace of the author:
<p>I have lived in the following countries (given in the order of when I first lived there):</p> <ol> <li>United Kingdom</li> <li>Switzerland</li> <li>United States</li> <li>Norway</li> </ol>
4.4.7. The ul
element
- Categories:
- Flow content.
- If the element’s children include at least one
li
element: Palpable content. - Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Zero or more
li
and script-supporting elements. - Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
list
role (default - do not set),directory
,group
,listbox
,menu
,menubar
,presentation
,radiogroup
,tablist
,toolbar
ortree
. - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLUListElement
: HTMLElement {};
The ul
element represents a list of items, where the order of the items is not
important — that is, where changing the order would not materially change the meaning of the
document.
The items of the list are the li
element child nodes of the ul
element.
ul
element is therefore appropriate. Compare this list to the equivalent list in the ol
section to see an example of the same items using the ol
element.
<p>I have lived in the following countries:</p> <ul> <li>Norway</li> <li>Switzerland</li> <li>United Kingdom</li> <li>United States</li> </ul>
Note that changing the order of the list does not change the meaning of the document. The items in the snippet above are given in alphabetical order, but in the snippet below they are given in order of the size of their current account balance in 2007, without changing the meaning of the document whatsoever:
<p>I have lived in the following countries:</p> <ul> <li>Switzerland</li> <li>Norway</li> <li>United Kingdom</li> <li>United States</li> </ul>
4.4.8. The li
element
- Categories:
- None.
- Contexts in which this element can be used:
- Inside
ol
elements. - Inside
ul
elements. - Content model:
- Flow content.
- Tag omission in text/html:
- An
li
element’s end tag may be omitted if theli
element is immediately followed by anotherli
element or if there is no more content in the parent element. - Content attributes:
- Global attributes
- If the element is not a child of an
ul
:value
- Allowed ARIA role attribute values:
-
listitem
role (default - do not set),menuitem
,menuitemcheckbox
,menuitemradio
,option
,none
,presentation
,radio
,separator
,tab
ortreeitem
. - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLLIElement
: HTMLElement { attribute long value; }; - DPub Roles:
-
doc-biblioentry
ordoc-endnote
The li
element represents a list item. If its parent element is an ol
, or ul
, 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.
If the parent element is an ol
element, then the li
element has an ordinal value.
The value
attribute, if present, must be a valid integer giving the ordinal value of the 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, the attribute must be treated as if it 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
IDL attribute must reflect the value of the value
content attribute.
figure
element and its figcaption
element.
<figure> <figcaption>The top 10 movies of all time</figcaption> <ol> <li value="10"><cite>Josie and the Pussycats</cite>, 2001</li> <li value="9"><cite lang="sr">Црна мачка, бели мачор</cite>, 1998</li> <li value="8"><cite>A Bug’s Life</cite>, 1998</li> <li value="7"><cite>Toy Story</cite>, 1995</li> <li value="6"><cite>Monsters, Inc</cite>, 2001</li> <li value="5"><cite>Cars</cite>, 2006</li> <li value="4"><cite>Toy Story 2</cite>, 1999</li> <li value="3"><cite>Finding Nemo</cite>, 2003</li> <li value="2"><cite>The Incredibles</cite>, 2004</li> <li value="1"><cite>Ratatouille</cite>, 2007</li> </ol> </figure>
The markup could also be written as follows, using the reversed
attribute on the ol
element:
<figure> <figcaption>The top 10 movies of all time</figcaption> <ol reversed> <li><cite>Josie and the Pussycats</cite>, 2001</li> <li><cite lang="sr">Црна мачка, бели мачор</cite>, 1998</li> <li><cite>A Bug’s Life</cite>, 1998</li> <li><cite>Toy Story</cite>, 1995</li> <li><cite>Monsters, Inc</cite>, 2001</li> <li><cite>Cars</cite>, 2006</li> <li><cite>Toy Story 2</cite>, 1999</li> <li><cite>Finding Nemo</cite>, 2003</li> <li><cite>The Incredibles</cite>, 2004</li> <li><cite>Ratatouille</cite>, 2007</li> </ol> </figure>
While it is conforming to include heading elements (e.g., h2
) and Sectioning content inside li
elements, it likely does not convey the
semantics that the author intended. A heading starts a new section, so a heading in a list
implicitly splits the list into spanning multiple sections. Sectioning content explicitly
creates a new section and so splits the list into spanning multiple sections.
4.4.9. The dl
element
- Categories:
- Flow content.
- If the element’s children include at least one name-value group: Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Either:Zero or more groups each consisting of one or more
dt
elements followed by one or moredd
elements, optionally intermixed with script-supporting elements. - Or: One or more
div
elements, optionally intermixed with script-supporting elements. - Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
list
role (default - do not set),group
,none
orpresentation
. - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLDListElement
: HTMLElement {}; - DPub Roles:
-
doc-glossary
The dl
element represents a description list of zero or more term-description groups.
Each term-description group consists of one or more terms (represented by dt
elements)
and one or more descriptions (represented by dd
elements.
The div
element may be used as a child of the dl
element (as a way to organize term-description groups consisting of one or more more dt
elements, and one or more dd
elements).
Term-description groups may be names and definitions, questions and answers, categories and topics, or any other groups of term-description pairs.
In this example a dl
is used to represent a simple list of names and descriptions:
<dl> <dt>Blanco tequila</dt> <dd>The purest form of the blue agave spirit...</dd> <dt>Reposado tequila</dt> <dd>Typically aged in wooden barrels for between two and eleven months...</dd> </dl>
Each term within a term-description group must be represented by a single dt
element.
The descriptions within a term-description group are alternatives. Each description must be
represented by a single dd
element.
In this example a dl
element represents a set of terms, each of which has multiple
descriptions:
<p>Information about the rock band Queen:</p> <dl> <dt>Members</dt> <dd>Brian May</dd> <dd>Freddie Mercury</dd> <dd>John Deacon</dd> <dd>Roger Taylor</dd> <dt>Record labels</dt> <dd>EMI</dd> <dd>Parlophone</dd> <dd>Capitol</dd> <dd>Hollywood</dd> <dd>Island</dd> </dl>
The div
element may be used to contain a term-description group, consisting of at least
one dt
and at least one dd
element.
In this example the div
element is used as a styling container for a term-description group:
<dl> <div class="teas"> <dt>Black teas</dt> <dd>Assam</dd> <dd>Darjeeling</dd> </div> <div> <dt>Green teas</dt> <dd>Gunpowder</dd> </div> </dl>
A div
element that is a child of a dl
element, must contain at least one term-description group consisting of at least one dt
element and at least one dd
element.
In this example the div
element is ignored because it does not contain a term-description group:
<dl> <div> <p>Important questions:</p> </div> <dt>What is the answer to life, the universe, and everything?</dt> <dd>42</dd> </dl>
The order of term-description groups within a dl
element, and the order of terms and
descriptions within each group, may be significant.
In this example a dl
is used to show a set of instructions, where the order of the
instructions is important:
<p>Determine the victory points as follows (use the first matching case):</p> <dl> <dt> If you have exactly five gold coins </dt> <dd> You get five victory points </dd> <dt> If you have one or more gold coins, and you have one or more silver coins </dt> <dd> You get two victory points </dd> <dt> If you have one or more silver coins </dt> <dd> You get one victory point </dd> <dt> Otherwise </dt> <dd> You get no victory points </dd> </dl>
If a dl
element contains no dt
or dd
child elements, it contains no term-description groups.
When a dl
element does not match its content model, it is often because
a dd
element has been used instead of a dt
element, or vice versa.
4.4.10. The dt
element
- Categories:
- None.
- Contexts in which this element can be used:
- Before
dd
ordt
elements insidedl
elements. - Content model:
- Flow content, but with no
header
,footer
, sectioning content, or heading content descendants. - Tag omission in text/html:
- A
dt
element’s end tag may be omitted if thedt
element is immediately followed by anotherdt
element or add
element. - Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
listitem
role (default - do not set) - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default role. - DOM interface:
- Uses
HTMLElement
.
The dt
element represents a term, part of a term-description group in a description list (dl
element).
In this example the dt
elements represent questions and the dd
elements the answers:
<dl> <dt>What is my favorite drink?</dt> <dd>Tea</dd> <dt>What is my favorite food?</dt> <dd>Sushi</dd> <dt>What is my favourite film?</dt> <dd>What a Wonderful Life</dd> </dl>
When used within a dl
element, the dt
element does not necessarily represent a term being defined. The dfn
element should be used to represent a term being defined.
In this example the dfn
element indicates that the dt
element contains a defined term, the definition for which is represented by the dd
element:
<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>
4.4.11. The dd
element
- Categories:
- None.
- Contexts in which this element can be used:
- After
dt
ordd
elements insidedl
elements. - Content model:
- Flow content.
- Tag omission in text/html:
- A
dd
element’s end tag may be omitted if thedd
element is immediately followed by anotherdd
element or adt
element, or if there is no more content in the parent element. - Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
definition
role (default - do not set) - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
- Uses
HTMLElement
.
The dd
element represents a description, part of a term-description group in a description list (dl
element).
In this example the dd
elements represent the keys that invoke the keycodes indicated in the dt
elements:
<dl> <dt>37</dt> <dd>Left</dd> <dt>38</dt> <dd>Right</dd> <dt>39</dt> <dd>Up</dd> <dt>40</dt> <dd>Down</dd> </dl>
4.4.12. The figure
element
- Categories:
- Flow content.
- Sectioning root.
- Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected.
- Content model:
- Flow content optionally including a
figcaption
child element. - Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
figure
role (default - do not set),group
,none
orpresentation
. - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
- Uses
HTMLElement
.
The figure
element represents some flow content, optionally with a
caption, that is self-contained (like a complete sentence) and is typically referenced as a single
unit from the main flow of the document.
"Self-contained" in this context does not necessarily mean independent. For example, each sentence
in a paragraph is self-contained; an image that is part of a sentence would be inappropriate for figure
, but an entire sentence made of images would be fitting.
The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.
figure
is referred to from the main content of the document by identifying
it by its caption (e.g., by figure number), it enables such content to be easily moved away from
that primary content, e.g., to the side of the page, to dedicated pages, or to an appendix,
without affecting the flow of the document.
If a figure
element is referenced by its relative position, e.g., "in the photograph
above" or "as the next figure shows", then moving the figure would disrupt the page’s meaning.
Authors are encouraged to consider using labels to refer to figures, rather than using such
relative references, so that the page can easily be restyled without affecting the page’s
meaning.
The figcaption
descendant of figure
, if any, represents the caption of the figure
element’s contents. If there is no child figcaption
element, then there is no caption.
A figure
element’s contents are part of the surrounding flow. If the purpose of the
page is to display the figure, for example a photograph on an image sharing site, the figure
and figcaption
elements can be used to explicitly provide a
caption for that figure. For content that is only tangentially related, or that serves a separate
purpose than the surrounding flow, the aside
element should be used (and can itself
wrap a figure
). For example, a pull quote that repeats content from an article
would be more appropriate in an aside
than in a figure
, because it isn’t part of the content, it’s a repetition of the content for
the purposes of enticing readers or highlighting key topics.
figure
element to mark up a code listing.
<p>In <a href="#l4">listing 4</a> we see the primary core interface API declaration.</p> <figure id="l4"> <figcaption>Listing 4. The primary core interface API declaration.</figcaption> <pre><code>interface PrimaryCore { boolean verifyDataLine(); void sendData(in sequence<byte> data); void initSelfDestruct(); }</code></pre> </figure> <p>The API is designed to use UTF-8.</p>
figure
element to mark up a photo that is the main content of the
page (as in a gallery).
<!DOCTYPE html> <title>Bubbles at work — My Gallery™</title> <figure> <img src="bubbles-work.jpeg" alt="Bubbles, sitting in his office chair, works on his latest project intently."> <figcaption>Bubbles at work</figcaption> </figure> <nav><a href="19414.html">Prev</a> — <a href="19416.html">Next</a></nav>
figure
would be inappropriate.
<h2>Malinko’s comics</h2> <p>This case centered on some sort of "intellectual property" infringement related to a comic (see Exhibit A). The suit started after a trailer ending with these words:</p> <blockquote> <img src="promblem-packed-action.png" alt="ROUGH COPY! Promblem-Packed Action!"> </blockquote> <p>...was aired. A lawyer, armed with a Bigger Notebook, launched a preemptive strike using snowballs. A complete copy of the trailer is included with Exhibit B.</p> <figure> <img src="ex-a.png" alt="Two squiggles on a dirty piece of paper."> <figcaption>Exhibit A. The alleged <cite>rough copy</cite> comic.</figcaption> </figure> <figure> <video src="ex-b.mov"></video> <figcaption>Exhibit B. The <cite>Rough Copy</cite> trailer.</figcaption> </figure> <p>The case was resolved out of court.</p>
figure
.
<figure> <p>'Twas brillig, and the slithy toves<br> Did gyre and gimble in the wabe;<br> All mimsy were the borogoves,<br> And the mome raths outgrabe.</p> <figcaption><cite>Jabberwocky</cite> (first verse). Lewis Carroll, 1832-98</figcaption> </figure>
figure
elements are used to provide both a group caption and individual captions for
each figure in the group:
<figure> <figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption> <figure> <figcaption>Etching. Anonymous, ca. 1423.</figcaption> <img src="castle1423.jpeg" alt="The castle has one tower, and a tall wall around it."> </figure> <figure> <figcaption>Oil-based paint on canvas. Maria Towle, 1858.</figcaption> <img src="castle1858.jpeg" alt="The castle now has two towers and two walls."> </figure> <figure> <figcaption>Film photograph. Peter Jankle, 1999.</figcaption> <img src="castle1999.jpeg" alt="The castle lies in ruins, the original tower all that remains in one piece."> </figure> </figure>
<article> <h1>Fiscal negotiations stumble in Congress as deadline nears</h1> <figure> <img src="obama-reid.jpeg" alt="Obama and Reid sit together smiling in the Oval Office."> <figcaption>Barack Obama and Harry Reid. White House press photograph.</figcaption> </figure> <p>Negotiations in Congress to end the fiscal impasse sputtered on Tuesday, leaving both chambers grasping for a way to reopen the government and raise the country’s borrowing authority with a Thursday deadline drawing near.</p> ... </article>
4.4.13. The figcaption
element
- Categories:
- None.
- Contexts in which this element can be used:
- As a descendant of a
figure
element. - Content model:
- Flow content.
- Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
group
,none
orpresentation
. - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
- Uses
HTMLElement
.
The figcaption
element represents a caption or legend for the rest of the
contents of the figcaption
element’s parent figure
element, if any.
4.4.14. The main
element
- Categories:
- Flow content.
- Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected, but only if it is a hierarchically correct main element.
- Content model:
- Flow content.
- Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
-
main
role (default - do not set). - Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default role. - DOM interface:
- Uses
HTMLElement
The main
element represents the dominant contents of the document.
A document must not have more than one main
element that does not have the §5.1 The hidden attribute attribute specified.
A hierarchically correct main element is one whose ancestor elements are limited to html
, body
, div
, form
without an accessible name, and autonomous custom elements. Each main
element must be a hierarchically correct main element.
The main
element is not sectioning content and has no effect on the document outline.
The main
element is not suitable for identifying the main content areas of sub-sections of a document. The simplest solution is not to mark up the main content of a sub-section at all (leaving it as implicit), but an author could use §4.4 Grouping content or a sectioning content element as appropriate.
<!-- conforming example --> <main>...</main> <main hidden>...</main> <main hidden>...</main> <!-- non-conforming example --> <main>...</main> <main>...</main> <main>...</main>
In the following example, we see 2 articles about skateboards (the main topic of a Web page) the
main topic content is identified by the use of the main
element.
<!-- other content --> <main> <h1>Skateboards</h1> <p>The skateboard is the way cool kids get around</p> <article> <h2>Longboards</h2> <p>Longboards are a type of skateboard with a longer wheelbase and larger, softer wheels.</p> <p>... </p> <p>... </p> </article> <article> <h2>Electric Skateboards</h2> <p>These no longer require the propelling of the skateboard by means of the feet; rather an electric motor propels the board, fed by an electric battery.</p> <p>... </p> <p>... </p> </article> </main> <!-- other content -->
Here is a graduation programme, in which the main content section is defined by the use of the main
element. Note in this example the main
element contains a nav
element consisting of links to sub sections of the main content.
<html lang="en"> <head> <title>Graduation Ceremony Summer 2022</title> </head> <body> <header>The Lawson Academy: <nav> <ul> <li><a href="courses.html">Courses</a></li> <li><a href="fees.html">Fees</a></li> <li><a>Graduation</a></li> </ul> </nav> </header> <main> <h1>Graduation</h1> <nav> <ul> <li><a href="#ceremony">Ceremony</a></li> <li><a href="#graduates">Graduates</a></li> <li><a href="#awards">Awards</a></li> </ul> </nav> <h2 id="ceremony">Ceremony</h2> <p>Opening Procession</p> <p>Speech by Valedictorian</p> <p>Speech by Class President</p> <p>Presentation of Diplomas</p> <p>Closing Speech by Headteacher</p> <h2 id="graduates">Graduates</h2> <ul> <li>Eileen Williams</li> <li>Andy Maseyk</li> <li>Blanca Sainz Garcia</li> <li>Clara Faulkner</li> <li>Gez Lemon</li> <li>Eloisa Faulkner</li> </ul> <h2 id="awards">Awards</h2> <ul> <li>Clara Faulkner</li> <li>Eloisa Faulkner</li> <li>Blanca Sainz Garcia</li> </ul> </main> <footer> Copyright 2012 B.lawson</footer> </body> </html>
In the next example, both the header
and the footer
are outside the main
element
because they are generic to the website and not specific to main
's content.
<!DOCTYPE html> <html lang="en"> <head> <title>Great Dogs for Families</title> </head> <body> <header> <h1>The Border Terrier</h1> <nav> <ul> <li><a href="index.html">Home</a></li> <li><a href="about.html">About</a></li> <li><a href="health.html">Health</a></li> </ul> </nav> </header> <main> <h2>Welcome!</h2> <p>This site is all about the Border Terrier, the best breed of dog that there is!</p> </main> <footer> <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small> </footer> </body> </html>
Here, the same generic header
and footer
elements remain outside main
, but there
is an additional header
element within the main
element as its content is relevant to
the content within main
because it contains a relevant heading and in-page navigation.
The in-page navigation is repeated within a footer
which is again within the main
element.
<!DOCTYPE html> <html lang="en"> <head> <title>Great Dogs for Families</title> </head> <body> <header> <h1>The Border Terrier</h1> <nav> <ul> <li><a href="index.html">Home</a></li> <li><a href="about.html">About</a></li> <li><a href="health.html">Health</a></li> </ul> </nav> </header> <main> <section> <header> <h2>About</h2> <nav> <ul> <li><a href="#basic">Basic</a></li> <li><a href="#app">Appearance</a></li> <li><a href="#temp">Temperament</a></li> </ul> </nav> </header> <section id="basic"> <h3>Basic Information</h3> <p>The Border Terrier is a small, rough-coated breed of dog of the terrier group, originally bred as fox and vermin hunters. [...]</p> </section> <section id="app"> <h3>Appearance</h3> <p>Identifiable by their otter-shaped heads, Border Terriers have a broad skull and short (although many be fairly long), strong muzzle with a scissors bite. [...]</p> </section> <section id="temp"> <h3>Temperament</h3> <p>Though sometimes stubborn and strong willed, border terriers are, on the whole very even tempered, and are friendly and rarely aggressive. [...] </p> </section> <footer> <a href="#basic">Basic</a> - <a href="#app">Appearance</a> - <a href="#temp">Temperament</a> </footer> </section> </main> <footer> <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small> </footer> </body> </html>
This example is largely the same as the previous one except that it includes an aside
.
The content of the aside
is considered to be relevant to the content within the main
element, which is all about the Border Terrier, so the aside
is placed within the main
element.
<!DOCTYPE html> <html lang="en"> <head> <title>Great Dogs for Families</title> </head> <body> <header> <h1>The Border Terrier</h1> <nav> <ul> <li><a href="index.html">Home</a></li> <li><a href="about.html">About</a></li> <li><a href="health.html">Health</a></li> </ul> </nav> </header> <main> <section> <header> <h2>About</h2> <nav> <ul> <li><a href="#basic">Basic</a></li> <li><a href="#app">Appearance</a></li> <li><a href="#temp">Temperament</a></li> </ul> </nav> </header> <section id="basic"> <h3>Basic Information</h3> <p>The Border Terrier is a small, rough-coated breed of dog of the terrier group, originally bred as fox and vermin hunters. [...]</p> </section> <section id="app"> <h3>Appearance</h3> <p>Identifiable by their otter-shaped heads, Border Terriers have a broad skull and short (although many be fairly long), strong muzzle with a scissors bite. [...]</p> </section> <section id="temp"> <h3>Temperament</h3> <p>Though sometimes stubborn and strong willed, border terriers are, on the whole very even tempered, and are friendly and rarely aggressive. [...] </p> </section> <aside> <h3>History</h3> <p>The Border Terrier originates in, and takes its name from the Scottish borders. [...] </p> </aside> <footer> <a href="#basic">Basic</a> - <a href="#app">Appearance</a> - <a href="#temp">Temperament</a> </footer> </section> </main> <footer> <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small> </footer> </body> </html>
In the following example, two aside
elements containg adverts have been placed outside
the main
element as their content is not specific to the content within main
. These aside
s could be on any page, as they are as generic as the header
and footer
shown.
<!DOCTYPE html> <html lang="en"> <head> <title>Great Dogs for Families</title> </head> <body> <header> <h1>The Border Terrier</h1> <nav> <ul> <li><a href="index.html">Home</a></li> <li><a href="about.html">About</a></li> <li><a href="health.html">Health</a></li> </ul> </nav> </header> <main> <h2>Welcome!</h2> <p>This site is all about the Border Terrier, the best breed of dog that there is!</p> </main> <aside class="advert"> <h2>Border Farm Breeders</h2> <p>We are a certified breeder of Border Terriers, contact us at...</p> </aside> <aside class="advert"> <h2>Grumpy’s Pet Shop</h2> <p>Get all your pet’s needs at our shop!</p> </aside> <footer> <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small> </footer> </body> </html>
4.4.15. The div
element
- Categories:
- Flow content.
- Palpable content.
- Contexts in which this element can be used:
- Where flow content is expected.
- As a child of a
dl
element. - Content model:
- If the element is a child of a
dl
element: one or moredt
elements followed by one or moredd
elements, optionally intermixed with script-supporting elements. - If the element is not a child of a
dl
element: Flow content. - Tag omission in text/html:
- Neither tag is omissible
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
- Any role value.
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - DOM interface:
-
interface
HTMLDivElement
: HTMLElement {};
The div
element has no special meaning at all. It represents its children. It
can be used with the class
, lang
, and title
attributes to
mark up semantics common to a group of consecutive elements.
Authors are strongly encouraged to view the div
element as an element of last
resort, for when no other element is suitable. Use of more appropriate elements instead of the div
element leads to better accessibility for readers and easier maintainability
for authors.
article
, a chapter using section
, a page’s navigation aids using nav
, and a group of form
controls using fieldset
.
On the other hand, div
elements can be useful for stylistic purposes or to wrap
multiple paragraphs within a section that are all to be annotated in a similar way. In the
following example, we see div
elements used as a way to set the language of two
paragraphs at once, instead of setting the language on the two paragraph elements separately:
<article lang="en-US"> <h2>My use of language and my cats</h2> <p>My cat’s behavior hasn’t changed much since her absence, except that she plays her new physique to the neighbors regularly, in an attempt to get pets.</p> <div lang="en-GB"> <p>My other cat, colored black and white, is a sweetie. He followed us to the pool today, walking down the pavement with us. Yesterday he apparently visited our neighbours. I wonder if he recognizes that their flat is a mirror image of ours.</p> <p>Hm, I just noticed that in the last paragraph I used British English. But I’m supposed to write in American English. So I shouldn’t say "pavement" or "flat" or "color"...</p> </div> <p>I should say "sidewalk" and "apartment" and "color"!</p> </article>