W3C

HTML 5

A vocabulary and associated APIs for HTML and XHTML

← 4.6 Text-level semanticsTable of contents4.8.7 The video element →

4.8 Embedded content

4.8.1 The figure element

Categories
Flow content.
Sectioning root.
Contexts in which this element may be used:
Where flow content is expected.
Content model:
Either: one legend element followed by flow content.
Or: Flow content followed by one legend element.
Or: Flow content.
Content attributes:
Global attributes
DOM interface:
Uses HTMLElement.

The figure element represents some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document.

The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc, that are referred to from the main content of the document, but that could, without affecting the flow of the document, be moved away from that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix.

The first legend element child of the element, if any, represents the caption of the figure element's contents. If there is no child legend element, then there is no caption.

The remainder of the element's contents, if any, represents the content.

This example shows the 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">
 <legend>Listing 4. The primary core interface API declaration.</legend>
 <pre><code>interface PrimaryCore {
  boolean verifyDataLine();
  void sendData(in sequence&lt;byte> data);
  void initSelfDestruct();
}</code></pre>
</figure>
<p>The API is designed to use UTF-8.</p>

Here we see a figure element to mark up a photo.

<figure>
 <img src="bubbles-work.jpeg"
      alt="Bubbles, sitting in his office chair, works on his
           latest project intently.">
 <legend>Bubbles at work</legend>
</figure>

In this example, we see an image that is not a figure, as well as an image and a video that are.

<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>

<img src="promblem-packed-action.png" alt="ROUGH COPY! Promblem-Packed Action!">

<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.">
 <legend>Exhibit A. The alleged <cite>rough copy</cite> comic.</legend>
</figure>

<figure>
 <video src="ex-b.mov"></video>
 <legend>Exhibit B. The <code>Rough Copy</cite> trailer.</legend>
</figure>

<p>The case was resolved out of court.</p>

Here, a part of a poem is marked up using 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>
 <legend><cite>Jabberwocky</cite> (first verse). Lewis Carroll, 1832-98</legend>
</figure>

In this example, which could be part of a much larger work discussing a castle, the figure has three images in it.

<figure>
 <img src="castle1423.jpeg" title="Etching. Anonymous, ca. 1423."
      alt="The castle has one tower, and a tall wall around it.">
 <img src="castle1858.jpeg" title="Oil-based paint on canvas. Maria Towle, 1858."
      alt="The castle now has two towers and two walls.">
 <img src="castle1999.jpeg" title="Film photograph. Peter Jankle, 1999."
      alt="The castle lies in ruins, the original tower all that remains in one piece.">
 <legend>The castle through the ages: 1423, 1858, and 1999 respectively.</legend>
</figure>

4.8.2 The img element

Categories
Flow content.
Phrasing content.
Embedded content.
If the element has a usemap attribute: Interactive content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Empty.
Content attributes:
Global attributes
alt
src
usemap
ismap
width
height
DOM interface:
[NamedConstructor=Image(),
 NamedConstructor=Image(in unsigned long width),
 NamedConstructor=Image(in unsigned long width, in unsigned long height)]
interface HTMLImageElement : HTMLElement {
           attribute DOMString alt;
           attribute DOMString src;
           attribute DOMString useMap;
           attribute boolean isMap;
           attribute unsigned long width;
           attribute unsigned long height;
  readonly attribute boolean complete;
};

An img element represents an image.

The image given by the src attribute is the embedded content, and the value of the alt attribute is the img element's fallback content.

The src attribute must be present, and must contain a valid URL referencing a non-interactive, optionally animated, image resource that is neither paged nor scripted. If the base URI of the element is the same as the document's address, then the src attribute's value must not be the empty string.

Images can thus be static bitmaps (e.g. PNGs, GIFs, JPEGs), single-page vector documents (single-page PDFs, XML files with an SVG root element), animated bitmaps (APNGs, animated GIFs), animated vector graphics (XML files with an SVG root element that use declarative SMIL animation), and so forth. However, this also precludes SVG files with script, multipage PDF files, interactive MNG files, HTML documents, plain text documents, and so forth.

The requirements on the alt attribute's value are described in the next section.

The img must not be used as a layout tool. In particular, img elements should not be used to display transparent images, as they rarely convey meaning and rarely add anything useful to the document.


Unless the user agent cannot support images, or its support for images has been disabled, or the user agent only fetches elements on demand, or the element's src attribute has a value that is an ignored self-reference, then, when an img is created with a src attribute, and whenever the src attribute is set subsequently, the user agent must resolve the value of that attribute, relative to the element, and if that is successful must then fetch that resource.

The src attribute's value is an ignored self-reference if its value is the empty string, and the base URI of the element is the same as the document's address.

Fetching the image must delay the load event of the element's document until the task that is queued by the networking task source once the resource has been fetched (defined below) has been run.

This, unfortunately, can be used to perform a rudimentary port scan of the user's local network (especially in conjunction with scripting, though scripting isn't actually necessary to carry out such an attack). User agents may implement cross-origin access control policies that mitigate this attack.

If the image is in a supported image type and its dimensions are known, then the image is said to be available (this affects exactly what the element represents, as defined below). This can be true even before the image is completely downloaded, if the user agent supports incremental rendering of images; in such cases, each task that is queued by the networking task source while the image is being fetched must update the presentation of the image appropriately. It can also stop being true, e.g. if the user agent finds, after obtaining the image's dimensions, that the image data is actually fatally corrupted.

If the image was not fetched (e.g. because the UA's image support is disabled, or because the src attribute's value is an ignored self-reference), or if the conditions in the previous paragraph are not met, then the image is not available.

An image might be available in one view but not another. For instance, a Document could be rendered by a screen reader providing a speech synthesis view of the output of a Web browser using the screen media. In this case, the image would be available in the Web browser's screen view, but not available in the screen reader's view.

Whether the image is fetched successfully or not (e.g. whether the response code was a 2xx code or equivalent) must be ignored when determining the image's type and whether it is a valid image.

This allows servers to return images with error responses, and have them displayed.

The user agents should apply the image sniffing rules to determine the type of the image, with the image's associated Content-Type headers giving the official type. If these rules are not applied, then the type of the image must be the type given by the image's associated Content-Type headers.

User agents must not support non-image resources with the img element (e.g. XML files whose root element is an HTML element). User agents must not run executable code (e.g. scripts) embedded in the image resource. User agents must only display the first page of a multipage resource (e.g. a PDF file). User agents must not allow the resource to act in an interactive fashion, but should honor any animation in the resource.

This specification does not specify which image types are to be supported.

The task that is queued by the networking task source once the resource has been fetched, must act as appropriate given the following alternatives:

If the download was successful and the image is available
Queue a task to fire a simple event called load at the img element (this happens after complete starts returning true).
Otherwise (the fetching process failed without a response from the remote server, or completed but the image is not a supported image)
Queue a task to fire a simple event called error on the img element.

The task source for these tasks is the DOM manipulation task source.


What an img element represents depends on the src attribute and the alt attribute.

If the src attribute is set and the alt attribute is set to the empty string

The image is either decorative or supplemental to the rest of the content, redundant with some other information in the document.

If the image is available and the user agent is configured to display that image, then the element represents the image specified by the src attribute.

Otherwise, the element represents nothing, and may be omitted completely from the rendering. User agents may provide the user with a notification that an image is present but has been omitted from the rendering.

If the src attribute is set and the alt attribute is set to a value that isn't empty

The image is a key part of the content; the alt attribute gives a textual equivalent or replacement for the image.

If the image is available and the user agent is configured to display that image, then the element represents the image specified by the src attribute.

Otherwise, the element represents the text given by the alt attribute. User agents may provide the user with a notification that an image is present but has been omitted from the rendering.

If the src attribute is set and the alt attribute is not

The image might be a key part of the content, and there is no textual equivalent of the image available.

In a conforming document, the absence of the alt attribute indicates that the image is a key part of the content but that a textual replacement for the image was not available when the image was generated.

If the image is available, the element represents the image specified by the src attribute.

If the image is not available or if the user agent is not configured to display the image, then the user agent should display some sort of indicator that there is an image that is not being rendered, and may, if requested by the user, or if so configured, or when required to provide contextual information in response to navigation, provide caption information for the image, derived as follows:

  1. If the image has a title attribute whose value is not the empty string, then the value of that attribute is the caption information; abort these steps.

  2. If the image is the child of a figure element that has a child legend element, then the contents of the first such legend element are the caption information; abort these steps.

  3. Run the algorithm to create the outline for the document.

  4. If the img element did not end up associated with a heading in the outline, or if there are any other images that are lacking an alt attribute and that are associated with the same heading in the outline as the img element in question, then there is no caption information; abort these steps.

  5. The caption information is the heading with which the image is associated according to the outline.

If the src attribute is not set and either the alt attribute is set to the empty string or the alt attribute is not set at all

The element represents nothing.

Otherwise

The element represents the text given by the alt attribute.

The alt attribute does not represent advisory information. User agents must not present the contents of the alt attribute in the same way as content of the title attribute.

User agents may always provide the user with the option to display any image, or to prevent any image from being displayed. User agents may also apply image analysis heuristics to help the user make sense of the image when the user is unable to make direct use of the image, e.g. due to a visual disability or because they are using a text terminal with no graphics capabilities.

The contents of img elements, if any, are ignored for the purposes of rendering.


The usemap attribute, if present, can indicate that the image has an associated image map.

The ismap attribute, when used on an element that is a descendant of an a element with an href attribute, indicates by its presence that the element provides access to a server-side image map. This affects how events are handled on the corresponding a element.

The ismap attribute is a boolean attribute. The attribute must not be specified on an element that does not have an ancestor a element with an href attribute.

The img element supports dimension attributes.

The DOM attributes alt, src, useMap, and isMap each must reflect the respective content attributes of the same name.

image . width [ = value ]
image . height [ = value ]

These attributes return the actual rendered dimensions of the image, or zero if the dimensions are not known.

They can be set, to change the corresponding content attributes.

image . complete

Returns true if the image has been downloaded, decoded, and found to be valid; otherwise, returns false.

image = new Image( [ width [, height ] ] )

Returns a new img element, with the width and height attributes set to the values passed in the relevant arguments, if applicable.

The DOM attributes width and height must return the rendered width and height of the image, in CSS pixels, if the image is being rendered, and is being rendered to a visual medium; or else the intrinsic width and height of the image, in CSS pixels, if the image is available but not being rendered to a visual medium; or else 0, if the image is not available or its dimensions are not known. [CSS]

On setting, they must act as if they reflected the respective content attributes of the same name.

The DOM attribute complete must return true if the user agent has fetched the image specified in the src attribute, and it is in a supported image type (i.e. it was decoded without fatal errors), even if the final task queued by the networking task source for the fetching of the image resource has not yet been processed. Otherwise, the attribute must return false.

The value of complete can thus change while a script is executing.

Three constructors are provided for creating HTMLImageElement objects (in addition to the factory methods from DOM Core such as createElement()): Image(), Image(width), and Image(width, height). When invoked as constructors, these must return a new HTMLImageElement object (a new img element). If the width argument is present, the new object's width content attribute must be set to width. If the height argument is also present, the new object's height content attribute must be set to height.

A single image can have different appropriate alternative text depending on the context.

In each of the following cases, the same image is used, yet the alt text is different each time. The image is the coat of arms of the Canton Geneva in Switzerland.

Here it is used as a supplementary icon:

<p>I lived in <img src="carouge.svg" alt=""> Carouge.</p>

Here it is used as an icon representing the town:

<p>Home town: <img src="carouge.svg" alt="Carouge"></p>

Here it is used as part of a text on the town:

<p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt="The coat of arms depicts a lion, sitting in front of a tree."></p>
<p>It is used as decoration all over the town.</p>

Here it is used as a way to support a similar text where the description is given as well as, instead of as an alternative to, the image:

<p>Carouge has a coat of arms.</p>
<p><img src="carouge.svg" alt=""></p>
<p>The coat of arms depicts a lion, sitting in front of a tree.
It is used as decoration all over the town.</p>

Here it is used as part of a story:

<p>He picked up the folder and a piece of paper fell out.</p>
<p><img src="carouge.svg" alt="Shaped like a shield, the paper had a
red background, a green tree, and a yellow lion with its tongue
hanging out and whose tail was shaped like an S."></p>
<p>He stared at the folder. S! The answer he had been looking for all
this time was simply the letter S! How had he not seen that before? It all
came together now. The phone call where Hector had referred to a lion's tail,
the time Marco had stuck his tongue out...</p>

Here it is not known at the time of publication what the image will be, only that it will be a coat of arms of some kind, and thus no replacement text can be provided, and instead only a brief caption for the image is provided, in the title attribute:

<p>The last user to have uploaded a coat of arms uploaded this one:</p>
<p><img src="last-uploaded-coat-of-arms.cgi" title="User-uploaded coat of arms."></p>

Ideally, the author would find a way to provide real replacement text even in this case, e.g. by asking the previous user. Not providing replacement text makes the document more difficult to use for people who are unable to view images, e.g. blind users, or users or very low-bandwidth connections or who pay by the byte, or users who are forced to use a text-only Web browser.

Here are some more examples showing the same picture used in different contexts, with different appropriate alternate texts each time.

<article>
 <h1>My cats</h1>
 <h2>Fluffy</h2>
 <p>Fluffy is my favorite.</p>
 <img src="fluffy.jpg" alt="She likes playing with a ball of yarn.">
 <p>She's just too cute.</p>
 <h2>Miles</h2>
 <p>My other cat, Miles just eats and sleeps.</p>
</article>
<article>
 <h1>Photography</h1>
 <h2>Shooting moving targets indoors</h2>
 <p>The trick here is to know how to anticipate; to know at what speed and
 what distance the subject will pass by.</p>
 <img src="fluffy.jpg" alt="A cat flying by, chasing a ball of yarn, can be
 photographed quite nicely using this technique.">
 <h2>Nature by night</h2>
 <p>To achieve this, you'll need either an extremely sensitive film, or
 immense flash lights.</p>
</article>
<article>
 <h1>About me</h1>
 <h2>My pets</h2>
 <p>I've got a cat named Fluffy and a dog named Miles.</p>
 <img src="fluffy.jpg" alt="Fluffy, my cat, tends to keep itself busy.">
 <p>My dog Miles and I like go on long walks together.</p>
 <h2>music</h2>
 <p>After our walks, having emptied my mind, I like listening to Bach.</p>
</article>
<article>
 <h1>Fluffy and the Yarn</h1>
 <p>Fluffy was a cat who liked to play with yarn. He also liked to jump.</p>
 <aside><img src="fluffy.jpg" alt="" title="Fluffy"></aside>
 <p>He would play in the morning, he would play in the evening.</p>
</article>
4.8.2.1 Requirements for providing text to act as an alternative for images

The requirements for the alt attribute depend on what the image is intended to represent, as described in the following sections.

When an a element that is a hyperlink, or a button element, has no textual content but contains one or more images, the alt attributes must contain text that together convey the purpose of the link or button.

In this example, a user is asked to pick his preferred color from a list of three. Each color is given by an image, but for users who have configured their user agent not to display images, the color names are used instead:

<h1>Pick your color</h1>
<ul>
 <li><a href="green.html"><img src="green.jpeg" alt="Green"></a></li>
 <li><a href="blue.html"><img src="blue.jpeg" alt="Blue"></a></li>
 <li><a href="red.html"><img src="red.jpeg" alt="Red"></a></li>
</ul>

In this example, each button has a set of images to indicate the kind of color output desired by the user. The first image is used in each case to give the alternative text.

<button name="rgb"><img src="red" alt="RGB"><img src="green" alt=""><img src="blue" alt=""></button>
<button name="cmyk"><img src="cyan" alt="CMYK"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></button>

Since each image represents one part of the text, it could also be written like this:

<button name="rgb"><img src="red" alt="R"><img src="green" alt="G"><img src="blue" alt="B"></button>
<button name="cmyk"><img src="cyan" alt="C"><img src="magenta" alt="M"><img src="yellow" alt="Y"><img src="black" alt="K"></button>

However, with other alternative text, this might not work, and putting all the alternative text into one image in each case might make more sense:

<button name="rgb"><img src="red" alt="sRGB profile"><img src="green" alt=""><img src="blue" alt=""></button>
<button name="cmyk"><img src="cyan" alt="CMYK profile"><img src="magenta" alt=""><img src="yellow" alt=""><img src="black" alt=""></button>
4.8.2.1.2 A phrase or paragraph with an alternative graphical representation: charts, diagrams, graphs, maps, illustrations

Sometimes something can be more clearly stated in graphical form, for example as a flowchart, a diagram, a graph, or a simple map showing directions. In such cases, an image can be given using the img element, but the lesser textual version must still be given, so that users who are unable to view the image (e.g. because they have a very slow connection, or because they are using a text-only browser, or because they are listening to the page being read out by a hands-free automobile voice Web browser, or simply because they are blind) are still able to understand the message being conveyed.

The text must be given in the alt attribute, and must convey the same message as the image specified in the src attribute.

It is important to realize that the alternative text is a replacement for the image, not a description of the image.

In the following example we have a flowchart in image form, with text in the alt attribute rephrasing the flowchart in prose form:

<p>In the common case, the data handled by the tokenization stage
comes from the network, but it can also come from script.</p>
<p><img src="images/parsing-model-overview.png" alt="The network
passes data to the Tokenizer stage, which passes data to the Tree
Construction stage. From there, data goes to both the DOM and to
Script Execution. Script Execution is linked to the DOM, and, using
document.write(), passes data to the Tokenizer."></p>

Here's another example, showing a good solution and a bad solution to the problem of including an image in a description.

First, here's the good solution. This sample shows how the alternative text should just be what you would have put in the prose if the image had never existed.

<!-- This is the correct way to do things. -->
<p>
 You are standing in an open field west of a house.
 <img src="house.jpeg" alt="The house is white, with a boarded front door.">
 There is a small mailbox here.
</p>

Second, here's the bad solution. In this incorrect way of doing things, the alternative text is simply a description of the image, instead of a textual replacement for the image. It's bad because when the image isn't shown, the text doesn't flow as well as in the first example.

<!-- This is the wrong way to do things. -->
<p>
 You are standing in an open field west of a house.
 <img src="house.jpeg" alt="A white house, with a boarded front door.">
 There is a small mailbox here.
</p>

Text such as "Photo of white house with boarded door" would be equally bad alternative text (though it could be suitable for the title attribute or in the legend element of a figure with this image).

4.8.2.1.3 A short phrase or label with an alternative graphical representation: icons, logos

A document can contain information in iconic form. The icon is intended to help users of visual browsers to recognize features at a glance.

In some cases, the icon is supplemental to a text label conveying the same meaning. In those cases, the alt attribute must be present but must be empty.

Here the icons are next to text that conveys the same meaning, so they have an empty alt attribute:

<nav>
 <p><a href="/help/"><img src="/icons/help.png" alt=""> Help</a></p>
 <p><a href="/configure/"><img src="/icons/configuration.png" alt="">
 Configuration Tools</a></p>
</nav>

In other cases, the icon has no text next to it describing what it means; the icon is supposed to be self-explanatory. In those cases, an equivalent textual label must be given in the alt attribute.

Here, posts on a news site are labeled with an icon indicating their topic.

<body>
 <article>
  <header>
   <h1>Ratatouille wins <i>Best Movie of the Year</i> award</h1>
   <p><img src="movies.png" alt="Movies"></p>
  </header>
  <p>Pixar has won yet another <i>Best Movie of the Year</i> award,
  making this its 8th win in the last 12 years.</p>
 </article>
 <article>
  <header>
   <h1>Latest TWiT episode is online</h1>
   <p><img src="podcasts.png" alt="Podcasts"></p>
  </header>
  <p>The latest TWiT episode has been posted, in which we hear
  several tech news stories as well as learning much more about the
  iPhone. This week, the panelists compare how reflective their
  iPhones' Apple logos are.</p>
 </article>
</body>

Many pages include logos, insignia, flags, or emblems, which stand for a particular entity such as a company, organization, project, band, software package, country, or some such.

If the logo is being used to represent the entity, e.g. as a page heading, the alt attribute must contain the name of the entity being represented by the logo. The alt attribute must not contain text like the word "logo", as it is not the fact that it is a logo that is being conveyed, it's the entity itself.

If the logo is being used next to the name of the entity that it represents, then the logo is supplemental, and its alt attribute must instead be empty.

If the logo is merely used as decorative material (as branding, or, for example, as a side image in an article that mentions the entity to which the logo belongs), then the entry below on purely decorative images applies. If the logo is actually being discussed, then it is being used as a phrase or paragraph (the description of the logo) with an alternative graphical representation (the logo itself), and the first entry above applies.

In the following snippets, all four of the above cases are present. First, we see a logo used to represent a company:

<h1><img src="XYZ.gif" alt="The XYZ company"></h1>

Next, we see a paragraph which uses a logo right next to the company name, and so doesn't have any alternative text:

<article>
 <h2>News</h2>
 <p>We have recently been looking at buying the <img src="alpha.gif"
 alt=""> ΑΒΓ company, a small Greek company
 specializing in our type of product.</p>

In this third snippet, we have a logo being used in an aside, as part of the larger article discussing the acquisition:

 <aside><p><img src="alpha-large.gif" alt=""></p></aside>
 <p>The ΑΒΓ company has had a good quarter, and our
 pie chart studies of their accounts suggest a much bigger blue slice
 than its green and orange slices, which is always a good sign.</p>
</article>

Finally, we have an opinion piece talking about a logo, and the logo is therefore described in detail in the alternative text.

<p>Consider for a moment their logo:</p>

<p><img src="/images/logo" alt="It consists of a green circle with a
green question mark centered inside it."></p>

<p>How unoriginal can you get? I mean, oooooh, a question mark, how
<em>revolutionary</em>, how utterly <em>ground-breaking</em>, I'm
sure everyone will rush to adopt those specifications now! They could
at least have tried for some sort of, I don't know, sequence of
rounded squares with varying shades of green and bold white outlines,
at least that would look good on the cover of a blue book.</p>

This example shows how the alternative text should be written such that if the image isn't available, and the text is used instead, the text flows seamlessly into the surrounding text, as if the image had never been there in the first place.

4.8.2.1.4 Text that has been rendered to a graphic for typographical effect

Sometimes, an image just consists of text, and the purpose of the image is not to highlight the actual typographic effects used to render the text, but just to convey the text itself.

In such cases, the alt attribute must be present but must consist of the same text as written in the image itself.

Consider a graphic containing the text "Earth Day", but with the letters all decorated with flowers and plants. If the text is merely being used as a heading, to spice up the page for graphical users, then the correct alternative text is just the same text "Earth Day", and no mention need be made of the decorations:

<h1><img src="earthdayheading.png" alt="Earth Day"></h1>
4.8.2.1.5 A graphical representation of some of the surrounding text

In many cases, the image is actually just supplementary, and its presence merely reinforces the surrounding text. In these cases, the alt attribute must be present but its value must be the empty string.

In general, an image falls into this category if removing the image doesn't make the page any less useful, but including the image makes it a lot easier for users of visual browsers to understand the concept.

A flowchart that repeats the previous paragraph in graphical form:

<p>The network passes data to the Tokenizer stage, which
passes data to the Tree Construction stage. From there, data goes
to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to
the Tokenizer.</p>
<p><img src="images/parsing-model-overview.png" alt=""></p>

In these cases, it would be wrong to include alternative text that consists of just a caption. If a caption is to be included, then either the title attribute can be used, or the figure and legend elements can be used. In the latter case, the image would in fact be a phrase or paragraph with an alternative graphical representation, and would thus require alternative text.

<!-- Using the title="" attribute -->
<p>The network passes data to the Tokenizer stage, which
passes data to the Tree Construction stage. From there, data goes
to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to
the Tokenizer.</p>
<p><img src="images/parsing-model-overview.png" alt=""
        title="Flowchart representation of the parsing model."></p>
<!-- Using <figure> and <legend> -->
<p>The network passes data to the Tokenizer stage, which
passes data to the Tree Construction stage. From there, data goes
to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to
the Tokenizer.</p>
<figure>
 <img src="images/parsing-model-overview.png" alt="The Network leads
 to the Tokenizer, which leads to the Tree Construction. The Tree
 Construction leads to two items. The first is Script Execution, which
 leads via document.write() back to the Tokenizer. The second item
 from which Tree Construction leads is the DOM. The DOM is related to
 the Script Execution.">
 <legend>Flowchart representation of the parsing model.</legend>
</figure>
<!-- This is WRONG. Do not do this. Instead, do what the above examples do. -->
<p>The network passes data to the Tokenizer stage, which
passes data to the Tree Construction stage. From there, data goes
to both the DOM and to Script Execution. Script Execution is
linked to the DOM, and, using document.write(), passes data to
the Tokenizer.</p>
<p><img src="images/parsing-model-overview.png"
        alt="Flowchart representation of the parsing model."></p>
<!-- Never put the image's caption in the alt="" attribute! -->

A graph that repeats the previous paragraph in graphical form:

<p>According to a study covering several billion pages,
about 62% of documents on the Web in 2007 triggered the Quirks
rendering mode of Web browsers, about 30% triggered the Almost
Standards mode, and about 9% triggered the Standards mode.</p>
<p><img src="rendering-mode-pie-chart.png" alt=""></p>
4.8.2.1.6 A purely decorative image that doesn't add any information

In general, if an image is decorative but isn't especially page-specific, for example an image that forms part of a site-wide design scheme, the image should be specified in the site's CSS, not in the markup of the document.

However, a decorative image that isn't discussed by the surrounding text still has some relevance can be included in a page using the img element. Such images are decorative, but still form part of the content. In these cases, the alt attribute must be present but its value must be the empty string.

Examples where the image is purely decorative despite being relevant would include things like a photo of the Black Rock City landscape in a blog post about an event at Burning Man, or an image of a painting inspired by a poem, on a page reciting that poem. The following snippet shows an example of the latter case (only the first verse is included in this snippet):

<h1>The Lady of Shalott</h1>
<p><img src="shalott.jpeg" alt=""></p>
<p>On either side the river lie<br>
Long fields of barley and of rye,<br>
That clothe the wold and meet the sky;<br>
And through the field the road run by<br>
To many-tower'd Camelot;<br>
And up and down the people go,<br>
Gazing where the lilies blow<br>
Round an island there below,<br>
The island of Shalott.</p>

When a picture has been sliced into smaller image files that are then displayed together to form the complete picture again, one of the images must have its alt attribute set as per the relevant rules that would be appropriate for the picture as a whole, and then all the remaining images must have their alt attribute set to the empty string.

In the following example, a picture representing a company logo for XYZ Corp has been split into two pieces, the first containing the letters "XYZ" and the second with the word "Corp". The alternative text ("XYZ Corp") is all in the first image.

<h1><img src="logo1.png" alt="XYZ Corp"><img src="logo2.png" alt=""></h1>

In the following example, a rating is shown as three filled stars and two empty stars. While the alternative text could have been "★★★☆☆", the author has instead decided to more helpfully give the rating in the form "3 out of 5". That is the alternative text of the first image, and the rest have blank alternative text.

<p>Rating: <meter max=5 value=3><img src="1" alt="3 out of 5"
  ><img src="1" alt=""><img src="1" alt=""><img src="0" alt=""
  ><img src="0" alt=""></meter></p>

Generally, image maps should be used instead of slicing an image for links.

However, if an image is indeed sliced and any of the components of the sliced picture are the sole contents of links, then one image per link must have alternative text in its alt attribute representing the purpose of the link.

In the following example, a picture representing the flying spaghetti monster emblem, with each of the left noodly appendages and the right noodly appendages in different images, so that the user can pick the left side or the right side in an adventure.

<h1>The Church</h1>
<p>You come across a flying spaghetti monster. Which side of His
Noodliness do you wish to reach out for?</p>
<p><a href="?go=left" ><img src="fsm-left.png"  alt="Left side. "></a
  ><img src="fsm-middle.png" alt=""
  ><a href="?go=right"><img src="fsm-right.png" alt="Right side."></a></p>
4.8.2.1.9 A key part of the content

In some cases, the image is a critical part of the content. This could be the case, for instance, on a page that is part of a photo gallery. The image is the whole point of the page containing it.

How to provide alternative text for an image that is a key part of the content depends on the image's provenance.

The general case

When it is possible for detailed alternative text to be provided, for example if the image is part of a series of screenshots in a magazine review, or part of a comic strip, or is a photograph in a blog entry about that photograph, text that can serve as a substitute for the image must be given as the contents of the alt attribute.

A screenshot in a gallery of screenshots for a new OS, with some alternative text:

<figure>
 <img src="KDE%20Light%20desktop.png"
      alt="The desktop is blue, with icons along the left hand side in
           two columns, reading System, Home, K-Mail, etc. A window is
           open showing that menus wrap to a second line if they
           cannot fit in the window. The window has a list of icons
           along the top, with an address bar below it, a list of
           icons for tabs along the left edge, a status bar on the
           bottom, and two panes in the middle. The desktop has a bar
           at the bottom of the screen with a few buttons, a pager, a
           list of open applications, and a clock.">
 <legend>Screenshot of a KDE desktop.</legend>
</figure>

A graph in a financial report:

<img src="sales.gif"
     title="Sales graph"
     alt="From 1998 to 2005, sales increased by the following percentages
     with each year: 624%, 75%, 138%, 40%, 35%, 9%, 21%">

Note that "sales graph" would be inadequate alternative text for a sales graph. Text that would be a good caption is not generally suitable as replacement text.

Images that defy a complete description

In certain cases, the nature of the image might be such that providing thorough alternative text is impractical. For example, the image could be indistinct, or could be a complex fractal, or could be a detailed topographical map.

In these cases, the alt attribute must contain some suitable alternative text, but it may be somewhat brief.

Sometimes there simply is no text that can do justice to an image. For example, there is little that can be said to usefully describe a Rorschach inkblot test. However, a description, even if brief, is still better than nothing:

<figure>
 <img src="/commons/a/a7/Rorschach1.jpg" alt="A shape with left-right
 symmetry with indistinct edges, with a small gap in the center, two
 larger gaps offset slightly from the center, with two similar gaps
 under them. The outline is wider in the top half than the bottom
 half, with the sides extending upwards higher than the center, and
 the center extending below the sides.">
 <legend>A black outline of the first of the ten cards
 in the Rorschach inkblot test.</legend>
</figure>

Note that the following would be a very bad use of alternative text:

<!-- This example is wrong. Do not copy it. -->
<figure>
 <img src="/commons/a/a7/Rorschach1.jpg" alt="A black outline
 of the first of the ten cards in the Rorschach inkblot test.">
 <legend>A black outline of the first of the ten cards
 in the Rorschach inkblot test.</legend>
</figure>

Including the caption in the alternative text like this isn't useful because it effectively duplicates the caption for users who don't have images, taunting them twice yet not helping them any more than if they had only read or heard the caption once.

Another example of an image that defies full description is a fractal, which, by definition, is infinite in complexity.

The following example shows one possible way of providing alternative text for the full view of an image of the Mandelbrot set.

<img src="ms1.jpeg" alt="The Mandelbrot set appears as a cardioid with
its cusp on the real axis in the positive direction, with a smaller
bulb aligned along the same center line, touching it in the negative
direction, and with these two shapes being surrounded by smaller bulbs
of various sizes.">
Images whose contents are not known

In some unfortunate cases, there might be no alternative text available at all, either because the image is obtained in some automated fashion without any associated alternative text (e.g. a Webcam), or because the page is being generated by a script using user-provided images where the user did not provide suitable or usable alternative text (e.g. photograph sharing sites), or because the author does not himself know what the images represent (e.g. a blind photographer sharing an image on his blog).

In such cases, the alt attribute's value may be omitted, but one of the following conditions must be met as well:

Such cases are to be kept to an absolute minimum. If there is even the slightest possibility of the author having the ability to provide real alternative text, then it would not be acceptable to omit the alt attribute.

A photo on a photo-sharing site, if the site received the image with no metadata other than the caption:

<figure>
 <img src="1100670787_6a7c664aef.jpg">
 <legend>Bubbles traveled everywhere with us.</legend>
</figure>

It could also be marked up like this:

<article>
 <h1>Bubbles traveled everywhere with us.</h1>
 <img src="1100670787_6a7c664aef.jpg">
</article>

In either case, though, it would be better if a detailed description of the important parts of the image obtained from the user and included on the page.

A blind user's blog in which a photo taken by the user is shown. Initially, the user might not have any idea what the photo he took shows:

<article>
 <h1>I took a photo</h1>
 <p>I went out today and took a photo!</p>
 <figure>
  <img src="photo2.jpeg">
  <legend>A photograph taken blindly from my front porch.</legend>
 </figure>
</article>

Eventually though, the user might obtain a description of the image from his friends and could then include alternative text:

<article>
 <h1>I took a photo</h1>
 <p>I went out today and took a photo!</p>
 <figure>
  <img src="photo2.jpeg" alt="The photograph shows my hummingbird
  feeder hanging from the edge of my roof. It is half full, but there
  are no birds around. In the background, out-of-focus trees fill the
  shot. The feeder is made of wood with a metal grate, and it contains
  peanuts. The edge of the roof is wooden too, and is painted white
  with light blue streaks.">
  <legend>A photograph taken blindly from my front porch.</legend>
 </figure>
</article>

Sometimes the entire point of the image is that a textual description is not available, and the user is to provide the description. For instance, the point of a CAPTCHA image is to see if the user can literally read the graphic. Here is one way to mark up a CAPTCHA (note the title attribute):

<p><label>What does this image say?
<img src="captcha.cgi?id=8934" title="CAPTCHA">
<input type=text name=captcha></label>
(If you cannot see the image, you can use an <a
href="?audio">audio</a> test instead.)</p>

Another example would be software that displays images and asks for alternative text precisely for the purpose of then writing a page with correct alternative text. Such a page could have a table of images, like this:

<table>
 <thead>
  <tr> <th> Image <th> Description
 <tbody>
  <tr>
   <td> <img src="2421.png" title="Image 640 by 100, filename 'banner.gif'">
   <td> <input name="alt2421">
  <tr>
   <td> <img src="2422.png" title="Image 200 by 480, filename 'ad3.gif'">
   <td> <input name="alt2422">
</table>

Notice that even in this example, as much useful information as possible is still included in the title attribute.

Since some users cannot use images at all (e.g. because they have a very slow connection, or because they are using a text-only browser, or because they are listening to the page being read out by a hands-free automobile voice Web browser, or simply because they are blind), the alt attribute is only allowed to be omitted rather than being provided with replacement text when no alternative text is available and none can be made available, as in the above examples. Lack of effort from the part of the author is not an acceptable reason for omitting the alt attribute.

4.8.2.1.10 An image not intended for the user

Generally authors should avoid using img elements for purposes other than showing images.

If an img element is being used for purposes other than showing an image, e.g. as part of a service to count page views, then the alt attribute must be the empty string.

In such cases, the width and height attributes should both be set to zero.

4.8.2.1.11 An image in an e-mail or private document intended for a specific person who is known to be able to view images

This section does not apply to documents that are publicly accessible, or whose target audience is not necessarily personally known to the author, such as documents on a Web site, e-mails sent to public mailing lists, or software documentation.

When an image is included in a private communication (such as an HTML e-mail) aimed at a specific person who is known to be able to view images, the alt attribute may be omitted. However, even in such cases it is strongly recommended that alternative text be included (as appropriate according to the kind of image involved, as described in the above entries), so that the e-mail is still usable should the user use a mail client that does not support images, or should the document be forwarded on to other users whose abilities might not include easily seeing images.

4.8.2.1.12 General guidelines

The most general rule to consider when writing alternative text is the following: the intent is that replacing every image with the text of its alt attribute not change the meaning of the page.

So, in general, alternative text can be written by considering what one would have written had one not been able to include the image.

A corollary to this is that the alt attribute's value should never contain text that could be considered the image's caption, title, or legend. It is supposed to contain replacement text that could be used by users instead of the image; it is not meant to supplement the image. The title attribute can be used for supplemental information.

One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present. Whatever you say instead of the image is typically a good start for writing the alternative text.

4.8.2.1.13 Guidance for markup generators

Markup generators (such as WYSIWYG authoring tools) should, wherever possible, obtain alternative text from their users. However, it is recognized that in many cases, this will not be possible.

For images that are the sole contents of links, markup generators should examine the link target to determine the title of the target, or the URL of the target, and use information obtained in this manner as the alternative text.

As a last resort, implementors should either set the alt attribute to the empty string, under the assumption that the image is a purely decorative image that doesn't add any information but is still specific to the surrounding content, or omit the alt attribute altogether, under the assumption that the image is a key part of the content.

Markup generators should generally avoid using the image's own file name as the alternative text.

4.8.2.1.14 Guidance for conformance checkers

Conformance checkers must report the lack of an alt attribute as an error unless the conditions listed above for images whose contents are not known or they have been configured to assume that the document is an e-mail or document intended for a specific person who is known to be able to view images.

4.8.3 The iframe element

Categories
Flow content.
Phrasing content.
Embedded content.
Interactive content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Text that conforms to the requirements given in the prose.
Content attributes:
Global attributes
src
name
sandbox
seamless
width
height
DOM interface:
interface HTMLIFrameElement : HTMLElement {
           attribute DOMString src;
           attribute DOMString name;
           attribute DOMString sandbox;
           attribute boolean seamless;
           attribute DOMString width;
           attribute DOMString height;
  readonly attribute Document contentDocument;
  readonly attribute WindowProxy contentWindow;
};

The iframe element represents a nested browsing context.

The src attribute gives the address of a page that the nested browsing context is to contain. The attribute, if present, must be a valid URL. When the browsing context is created, if the attribute is present, the user agent must resolve the value of that attribute, relative to the element, and if that is successful, must then navigate the element's browsing context to the resulting absolute URL, with replacement enabled, and with the iframe element's document's browsing context as the source browsing context. If the user navigates away from this page, the iframe's corresponding WindowProxy object will proxy new Window objects for new Document objects, but the src attribute will not change.

Whenever the src attribute is set, the user agent must resolve the value of that attribute, relative to the element, and if that is successful, the nested browsing context must be navigated to the resulting absolute URL, with the iframe element's document's browsing context as the source browsing context.

If the src attribute is not set when the element is created, or if its value cannot be resolved, the browsing context will remain at the initial about:blank page.

The name attribute, if present, must be a valid browsing context name. The given value is used to name the nested browsing context. When the browsing context is created, if the attribute is present, the browsing context name must be set to the value of this attribute; otherwise, the browsing context name must be set to the empty string.

Whenever the name attribute is set, the nested browsing context's name must be changed to the new value. If the attribute is removed, the browsing context name must be set to the empty string.

When content loads in an iframe, after any load events are fired within the content itself, the user agent must fire a simple event called load at the iframe element. When content fails to load (e.g. due to a network error), then the user agent must fire a simple event called error at the element instead.

When there is an active parser in the iframe, and when anything in the iframe is delaying the load event of the iframe's browsing context's active document, the iframe must delay the load event of its document.

If, during the handling of the load event, the browsing context in the iframe is again navigated, that will further delay the load event.


The sandbox attribute, when specified, enables a set of extra restrictions on any content hosted by the iframe. Its value must be an unordered set of unique space-separated tokens. The allowed values are allow-same-origin, allow-forms, and allow-scripts. When the attribute is set, the content is treated as being from a unique origin, forms and scripts are disabled, links are prevented from targeting other browsing contexts, and plugins are disabled. The allow-same-origin token allows the content to be treated as being from the same origin instead of forcing it into a unique origin, and the allow-forms and allow-scripts tokens re-enable forms and scripts respectively (though scripts are still prevented from creating popups).

While the sandbox attribute is specified, the iframe element's nested browsing context, and all the browsing contexts nested within it (either directly or indirectly through other nested browsing contexts) must have the following flags set:

The sandboxed navigation browsing context flag

This flag prevents content from navigating browsing contexts other than the sandboxed browsing context itself (or browsing contexts further nested inside it).

This flag also prevents content from creating new auxiliary browsing contexts, e.g. using the target attribute or the window.open() method.

The sandboxed plugins browsing context flag

This flag prevents content from instantiating plugins, whether using the embed element, the object element, the applet element, or through navigation of a nested browsing context.

The sandboxed origin browsing context flag, unless the sandbox attribute's value, when split on spaces, is found to have the allow-same-origin keyword set

This flag forces content into a unique origin for the purposes of the same-origin policy.

This flag also prevents script from reading the document.cookie DOM attribute.

The allow-same-origin attribute is intended for two cases.

First, it can be used to allow content from the same site to be sandboxed to disable scripting, while still allowing access to the DOM of the sandboxed content.

Second, it can be used to embed content from a third-party site, sandboxed to prevent that site from opening popup windows, etc, without preventing the embedded page from communicating back to its originating site, using the database APIs to store data, etc.

This flag only takes effect when the nested browsing context of the iframe is navigated.

The sandboxed forms browsing context flag, unless the sandbox attribute's value, when split on spaces, is found to have the allow-forms keyword set

This flag blocks form submission.

The sandboxed scripts browsing context flag, unless the sandbox attribute's value, when split on spaces, is found to have the allow-scripts keyword set

This flag blocks script execution.

If the sandbox attribute is dynamically added after the iframe has loaded a page, scripts already compiled by that page (whether in script elements, or in event handler attributes, or elsewhere) will continue to run. Only new scripts will be prevented from executing by this flag.

These flags must not be set unless the conditions listed above define them as being set.

In this example, some completely-unknown, potentially hostile, user-provided HTML content is embedded in a page. Because it is sandboxed, it is treated by the user agent as being from a unique origin, despite the content being served from the same site. Thus it is affected by all the normal cross-site restrictions. In addition, the embedded page has scripting disabled, plugins disabled, forms disabled, and it cannot navigate any frames or windows other than itself (or any frames or windows it itself embeds).

<p>We're not scared of you! Here is your content, unedited:</p>
<iframe sandbox src="getusercontent.cgi?id=12193"></iframe>

Note that cookies are still sent to the server in the getusercontent.cgi request, though they are not visible in the document.cookie DOM attribute.

In this example, a gadget from another site is embedded. The gadget has scripting and forms enabled, and the origin sandbox restrictions are lifted, allowing the gadget to communicate with its originating server. The sandbox is still useful, however, as it disables plugins and popups, thus reducing the risk of the user being exposed to malware and other annoyances.

<iframe sandbox="allow-same-origin allow-forms allow-scripts"
        src="http://maps.example.com/embedded.html"></iframe>

The seamless attribute is a boolean attribute. When specified, it indicates that the iframe element's browsing context is to be rendered in a manner that makes it appear to be part of the containing document (seamlessly included in the parent document). Specifically, when the attribute is set on an element and while the browsing context's active document has the same origin as the iframe element's document, or the browsing context's active document's address has the same origin as the iframe element's document, the following requirements apply:

If the attribute is not specified, or if the origin conditions listed above are not met, then the user agent should render the nested browsing context in a manner that is clearly distinguishable as a separate browsing context, and the seamless browsing context flag must be set to false for that browsing context.

It is important that user agents recheck the above conditions whenever the active document of the nested browsing context of the iframe changes, such that the seamless browsing context flag gets unset if the nested browsing context is navigated to another origin.

The attribute can be set or removed dynamically, with the rendering updating in tandem.

In this example, the site's navigation is embedded using a client-side include using an iframe. Any links in the iframe will, in new user agents, be automatically opened in the iframe's parent browsing context; for legacy user agents, the site could also include a base element with a target attribute with the value _parent. Similarly, in new user agents the styles of the parent page will be automatically applied to the contents of the frame, but to support legacy user agents authors might wish to include the styles explicitly.

<nav><iframe seamless src="nav.include.html"></iframe></nav>

The iframe element supports dimension attributes for cases where the embedded content has specific dimensions (e.g. ad units have well-defined dimensions).

An iframe element never has fallback content, as it will always create a nested browsing context, regardless of whether the specified initial contents are successfully used.

Descendants of iframe elements represent nothing. (In legacy user agents that do not support iframe elements, the contents would be parsed as markup that could act as fallback content.)

When used in HTML documents, the allowed content model of iframe elements is text, except that invoking the HTML fragment parsing algorithm with the iframe element as the context element and the text contents as the input must result in a list of nodes that are all phrasing content, with no parse errors having occurred, with no script elements being anywhere in the list or as descendants of elements in the list, and with all the elements in the list (including their descendants) being themselves conforming.

The iframe element must be empty in XML documents.

The HTML parser treats markup inside iframe elements as text.

The DOM attributes src, name, sandbox, and seamless must reflect the respective content attributes of the same name.

The contentDocument DOM attribute must return the Document object of the active document of the iframe element's nested browsing context.

The contentWindow DOM attribute must return the WindowProxy object of the iframe element's nested browsing context.

4.8.4 The embed element

Categories
Flow content.
Phrasing content.
Embedded content.
Interactive content.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Empty.
Content attributes:
Global attributes
src
type
width
height
Any other attribute that has no namespace (see prose).
DOM interface:
interface HTMLEmbedElement : HTMLElement {
           attribute DOMString src;
           attribute DOMString type;
           attribute DOMString width;
           attribute DOMString height;
};

Depending on the type of content instantiated by the embed element, the node may also support other interfaces.

The embed element represents an integration point for an external (typically non-HTML) application or interactive content.

The src attribute gives the address of the resource being embedded. The attribute, if present, must contain a valid URL.

The type attribute, if present, gives the MIME type of the plugin to instantiate. The value must be a valid MIME type, optionally with parameters. If both the type attribute and the src attribute are present, then the type attribute must specify the same type as the explicit Content-Type metadata of the resource given by the src attribute.

When the element is created with neither a src attribute nor a type attribute, and when attributes are removed such that neither attribute is present on the element anymore, and when the element has a media element ancestor, and when the element has an ancestor object element that is not showing its fallback content, any plugins instantiated for the element must be removed, and the embed element represents nothing.

When the sandboxed plugins browsing context flag is set on the browsing context for which the embed element's document is the active document, then the user agent must render the embed element in a manner that conveys that the plugin was disabled. The user agent may offer the user the option to override the sandbox and instantiate the plugin anyway; if the user invokes such an option, the user agent must act as if the sandboxed plugins browsing context flag was not set for the purposes of this element.

Plugins are disabled in sandboxed browsing contexts because they might not honor the restrictions imposed by the sandbox (e.g. they might allow scripting even when scripting in the sandbox is disabled). User agents should convey the danger of overriding the sandbox to the user if an option to do so is provided.

When the element is created with a src attribute, and whenever the src attribute is subsequently set, and whenever the type attribute is set or removed while the element has a src attribute, if the element is not in a sandboxed browsing context, not a descendant of a media element, and not a descendant of an object element that is not showing its fallback content, the user agent must resolve the value of the attribute, relative to the element, and if that is successful, should fetch the resulting absolute URL. The task that is queued by the networking task source once the resource has been fetched must find and instantiate an appropriate plugin based on the content's type, and hand that plugin the content of the resource, replacing any previously instantiated plugin for the element.

Fetching the resource must delay the load event of the element's document.

The type of the content being embedded is defined as follows:

  1. If the element has a type attribute, and that attribute's value is a type that a plugin supports, then the value of the type attribute is the content's type.

  2. Otherwise, if the <path> component of the URL of the specified resource (after any redirects) matches a pattern that a plugin supports, then the content's type is the type that that plugin can handle.

    For example, a plugin might say that it can handle resources with <path> components that end with the four character string ".swf".

  3. Otherwise, if the specified resource has explicit Content-Type metadata, then that is the content's type.

  4. Otherwise, the content has no type and there can be no appropriate plugin for it.

Whether the resource is fetched successfully or not (e.g. whether the response code was a 2xx code or equivalent) must be ignored when determining the resource's type and when handing the resource to the plugin.

This allows servers to return data for plugins even with error responses (e.g. HTTP 500 Internal Server Error codes can still contain plugin data).

When the element is created with a type attribute and no src attribute, and whenever the type attribute is subsequently set, so long as no src attribute is set, and whenever the src attribute is removed when the element has a type attribute, if the element is not in a sandboxed browsing context, user agents should find and instantiate an appropriate plugin based on the value of the type attribute.

Any (namespace-less) attribute may be specified on the embed element, so long as its name is XML-compatible and contains no characters in the range U+0041 .. U+005A (LATIN CAPITAL LETTER A LATIN CAPITAL LETTER Z).

All attributes in HTML documents get lowercased automatically, so the restriction on uppercase letters doesn't affect such documents.

The user agent should pass the names and values of all the attributes of the embed element that have no namespace to the plugin used, when it is instantiated.

If the plugin instantiated for the embed element supports a scriptable interface, the HTMLEmbedElement object representing the element should expose that interface while the element is instantiated.

The embed element has no fallback content. If the user agent can't find a suitable plugin, then the user agent must use a default plugin. (This default could be as simple as saying "Unsupported Format".)

The embed element supports dimension attributes.

The DOM attributes src and type each must reflect the respective content attributes of the same name.

4.8.5 The object element

Categories
Flow content.
Phrasing content.
Embedded content.
If the element has a usemap attribute: Interactive content.
Listed, submittable, form-associated element.
Contexts in which this element may be used:
Where embedded content is expected.
Content model:
Zero or more param elements, then, transparent.
Content attributes:
Global attributes
data
type
name
usemap
form
width
height
DOM interface:
interface HTMLObjectElement : HTMLElement {
           attribute DOMString data;
           attribute DOMString type;
           attribute DOMString name;
           attribute DOMString useMap;
  readonly attribute HTMLFormElement form;
           attribute DOMString width;
           attribute DOMString height;
  readonly attribute Document contentDocument;
  readonly attribute WindowProxy contentWindow;
};

Depending on the type of content instantiated by the object element, the node also supports other interfaces.

The object element can represent an external resource, which, depending on the type of the resource, will either be treated as an image, as a nested browsing context, or as an external resource to be processed by a plugin.

The data attribute, if present, specifies the address of the resource. If present, the attribute must be a valid URL.

The type attribute, if present, specifies the type of the resource. If present, the attribute must be a valid MIME type, optionally with parameters.

One or both of the data and type attributes must be present.

The name attribute, if present, must be a valid browsing context name. The given value is used to name the nested browsing context, if applicable.

When the element is created, and subsequently whenever the classid attribute changes or is removed, or, if the classid attribute is not present, whenever the data attribute changes or is removed, or, if neither classid attribute nor the data attribute are present, whenever the type attribute changes or is removed, the user agent must run the following steps to determine what the object element represents:

  1. If the element has an ancestor media element, or has an ancestor object element that is not showing its fallback content, then jump to the last step in the overall set of steps (fallback).

  2. If the classid attribute is present, and has a value that isn't the empty string, then: if the user agent can find a plugin suitable according to the value of the classid attribute, and plugins aren't being sandboxed, then that plugin should be used, and the value of the data attribute, if any, should be passed to the plugin. If no suitable plugin can be found, or if the plugin reports an error, jump to the last step in the overall set of steps (fallback).

  3. If the data attribute is present, then:

    1. If the type attribute is present and its value is not a type that the user agent supports, and is not a type that the user agent can find a plugin for, then the user agent may jump to the last step in the overall set of steps (fallback) without fetching the content to examine its real type.

    2. Resolve the URL specified by the data attribute, relative to the element.

      If that is successful, fetch the resulting absolute URL.

      Fetching the resource must delay the load event of the element's document until the task that is queued by the networking task source once the resource has been fetched (defined next) has been run.

    3. If the resource is not yet available (e.g. because the resource was not available in the cache, so that loading the resource required making a request over the network), then jump to the last step in the overall set of steps (fallback). The task that is queued by the networking task source once the resource is available must restart this algorithm from this step. Resources can load incrementally; user agents may opt to consider a resource "available" whenever enough data has been obtained to begin processing the resource.

    4. If the load failed (e.g. the URL could not be resolved, there was an HTTP 404 error, there was a DNS error), fire a simple event called error at the element, then jump to the last step in the overall set of steps (fallback).

    5. Determine the resource type, as follows:

      1. Let the resource type be unknown.

      2. If the resource has associated Content-Type metadata, then let the resource type be the type specified in the resource's Content-Type metadata.

      3. If the resource type is unknown or "application/octet-stream" and there is a type attribute present on the object element, then change the resource type to instead be the type specified in that type attribute.

        Otherwise, if the resource type is "application/octet-stream" but there is no type attribute on the object element, then change the resource type to be unknown, so that the sniffing rules in the next step are invoked.

      4. If the resource type is still unknown, then change the resource type to instead be the sniffed type of the resource.

    6. Handle the content as given by the first of the following cases that matches:

      If the resource type can be handled by a plugin and plugins aren't being sandboxed

      The user agent should use that plugin and pass the content of the resource to that plugin. If the plugin reports an error, then jump to the last step in the overall set of steps (fallback).

      If the resource type is an XML MIME type
      If the resource type is HTML
      If the resource type does not start with "image/"

      The object element must be associated with a nested browsing context, if it does not already have one. The element's nested browsing context must then be navigated to the given resource, with replacement enabled, and with the object element's document's browsing context as the source browsing context. (The data attribute of the object element doesn't get updated if the browsing context gets further navigated to other locations.)

      The object element represents the nested browsing context.

      If the name attribute is present, the browsing context name must be set to the value of this attribute; otherwise, the browsing context name must be set to the empty string.

      It's possible that the navigation of the browsing context will actually obtain the resource from a different application cache. Even if the resource is then found to have a different type, it is still used as part of a nested browsing context; this algorithm doesn't restart with the new resource.

      If the resource type starts with "image/", and support for images has not been disabled

      Apply the image sniffing rules to determine the type of the image.

      The object element represents the specified image. The image is not a nested browsing context.

      If the image cannot be rendered, e.g. because it is malformed or in an unsupported format, jump to the last step in the overall set of steps (fallback).

      Otherwise

      The given resource type is not supported. Jump to the last step in the overall set of steps (fallback).

    7. The element's contents are not part of what the object element represents.

    8. Once the resource is completely loaded, queue a task to fire a simple event called load at the element.

      The task source for this task is the DOM manipulation task source.

  4. If the data attribute is absent but the type attribute is present, plugins aren't being sandboxed, and the user agent can find a plugin suitable according to the value of the type attribute, then that plugin should be used. If no suitable plugin can be found, or if the plugin reports an error, jump to the next step (fallback).

  5. (Fallback.) The object element represents the element's children, ignoring any leading param element children. This is the element's fallback content.

When the algorithm above instantiates a plugin, the user agent should pass the names and values of all the attributes on the element, and all the names and values of parameters given by param elements that are children of the object element, in tree order, to the plugin used. If the plugin supports a scriptable interface, the HTMLObjectElement object representing the element should expose that interface. The object element represents the plugin. The plugin is not a nested browsing context.

If the sandboxed plugins browsing context flag is set on the browsing context for which the object element's document is the active document, then the steps above must always act as if they had failed to find a plugin, even if one would otherwise have been used.

Due to the algorithm above, the contents of object elements act as fallback content, used only when referenced resources can't be shown (e.g. because it returned a 404 error). This allows multiple object elements to be nested inside each other, targeting multiple user agents with different capabilities, with the user agent picking the first one it supports.

Whenever the name attribute is set, if the object element has a nested browsing context, its name must be changed to the new value. If the attribute is removed, if the object element has a browsing context, the browsing context name must be set to the empty string.

The usemap attribute, if present while the object element represents an image, can indicate that the object has an associated image map. The attribute must be ignored if the object element doesn't represent an image.

The form attribute is used to explicitly associate the object element with its form owner.

Constraint validation: object elements are always barred from constraint validation.

The object element supports dimension attributes.

The DOM attributes data, type, name, and useMap each must reflect the respective content attributes of the same name.

The contentDocument DOM attribute must return the Document object of the active document of the object element's nested browsing context, if it has one; otherwise, it must return null.

The contentWindow DOM attribute must return the WindowProxy object of the object element's nested browsing context, if it has one; otherwise, it must return null.

In the following example, a Java applet is embedded in a page using the object element. (Generally speaking, it is better to avoid using applets like these and instead use native JavaScript and HTML to provide the functionality, since that way the application will work on all Web browsers without requiring a third-party plugin. Many devices, especially embedded devices, do not support third-party technologies like Java.)

<figure>
 <object type="application/x-java-applet">
  <param name="code" value="MyJavaClass">
  <p>You do not have Java available, or it is disabled.</p>
 </object>
 <legend>My Java Clock</legend>
</figure>

In this example, an HTML page is embedded in another using the object element.

<figure>
 <object data="clock.html"></object>
 <legend>My HTML Clock</legend>
</figure>

4.8.6 The param element

Categories
None.
Contexts in which this element may be used:
As a child of an object element, before any flow content.
Content model:
Empty.
Content attributes:
Global attributes
name
value
DOM interface:
interface HTMLParamElement : HTMLElement {
           attribute DOMString name;
           attribute DOMString value;
};

The param element defines parameters for plugins invoked by object elements. It does not represent anything on its own.

The name attribute gives the name of the parameter.

The value attribute gives the value of the parameter.

Both attributes must be present. They may have any value.

If both attributes are present, and if the parent element of the param is an object element, then the element defines a parameter with the given name/value pair.

The DOM attributes name and value must both reflect the respective content attributes of the same name.