The data returned by getImageData() is at the
resolution of the canvas backing store, which is likely to not be
one device pixel to each CSS pixel if the display used is a high
resolution display.
In the following example, the script generates an
ImageData object so that it can draw onto it.
// canvas is a reference to a <canvas> element
var context = canvas.getContext('2d');
// create a blank slate
var data = context.createImageData(canvas.width, canvas.height);
// create some plasma
FillPlasma(data, 'green'); // green plasma
// add a cloud to the plasma
AddCloud(data, data.width/2, data.height/2); // put a cloud in the middle
// paint the plasma+cloud on the canvas
context.putImageData(data, 0, 0);
// support methods
function FillPlasma(data, color) { ... }
function AddCloud(data, x, y) { ... }
Here is an example of using getImageData() and putImageData() to
implement an edge detection filter.
<!DOCTYPE HTML>
<html>
<head>
<title>Edge detection demo</title>
<script>
var image = new Image();
function init() {
image.onload = demo;
image.src = "image.jpeg";
}
function demo() {
var canvas = document.getElementsByTagName('canvas')[0];
var context = canvas.getContext('2d');
// draw the image onto the canvas
context.drawImage(image, 0, 0);
// get the image data to manipulate
var input = context.getImageData(0, 0, canvas.width, canvas.height);
// get an empty slate to put the data into
var output = context.createImageData(canvas.width, canvas.height);
// alias some variables for convenience
// notice that we are using input.width and input.height here
// as they might not be the same as canvas.width and canvas.height
// (in particular, they might be different on high-res displays)
var w = input.width, h = input.height;
var inputData = input.data;
var outputData = output.data;
// edge detection
for (var y = 1; y < h-1; y += 1) {
for (var x = 1; x < w-1; x += 1) {
for (var c = 0; c < 3; c += 1) {
var i = (y*w + x)*4 + c;
outputData[i] = 127 + -inputData[i - w*4 - 4] - inputData[i - w*4] - inputData[i - w*4 + 4] +
-inputData[i - 4] + 8*inputData[i] - inputData[i + 4] +
-inputData[i + w*4 - 4] - inputData[i + w*4] - inputData[i + w*4 + 4];
}
outputData[(y*w + x)*4 + 3] = 255; // alpha
}
}
// put the image data back after manipulation
context.putImageData(output, 0, 0);
}
</script>
</head>
<body onload="init()">
<canvas></canvas>
</body>
</html>
When a shape or image is painted, user agents must follow these steps, in the order given (or act as if they do):
Render the shape or image onto an infinite transparent black bitmap, creating image A, as described in the previous sections. For shapes, the current fill, stroke, and line styles must be honored, and the stroke must itself also be subjected to the current transformation matrix.
When shadows are drawn, render the shadow from image A, using the current shadow styles, creating image B.
When shadows are drawn, multiply the alpha
component of every pixel in B by globalAlpha.
When shadows are drawn, composite B within the clipping region over the current canvas bitmap using the current composition operator.
Multiply the alpha component of every pixel in A by globalAlpha.
Composite A within the clipping region over the current canvas bitmap using the current composition operator.
This section is non-normative.
Here is an example of a script that uses canvas to draw pretty glowing lines.
<canvas width="800" height="450"></canvas>
<script>
var context = document.getElementsByTagName('canvas')[0].getContext('2d');
var lastX = context.canvas.width * Math.random();
var lastY = context.canvas.height * Math.random();
var hue = 0;
function line() {
context.save();
context.translate(context.canvas.width/2, context.canvas.height/2);
context.scale(0.9, 0.9);
context.translate(-context.canvas.width/2, -context.canvas.height/2);
context.beginPath();
context.lineWidth = 5 + Math.random() * 10;
context.moveTo(lastX, lastY);
lastX = context.canvas.width * Math.random();
lastY = context.canvas.height * Math.random();
context.bezierCurveTo(context.canvas.width * Math.random(),
context.canvas.height * Math.random(),
context.canvas.width * Math.random(),
context.canvas.height * Math.random(),
lastX, lastY);
hue = hue + 10 * Math.random();
context.strokeStyle = 'hsl(' + hue + ', 50%, 50%)';
context.shadowColor = 'white';
context.shadowBlur = 10;
context.stroke();
context.restore();
}
setInterval(line, 50);
function blank() {
context.fillStyle = 'rgba(0,0,0,0.1)';
context.fillRect(0, 0, context.canvas.width, context.canvas.height);
}
setInterval(blank, 40);
</script>
The canvas APIs must perform color correction at
only two points: when rendering images with their own gamma
correction and color space information onto the canvas, to convert
the image to the color space used by the canvas (e.g. using the 2D
Context's drawImage()
method with an HTMLImageElement object), and when
rendering the actual canvas bitmap to the output device.
Thus, in the 2D context, colors used to draw shapes
onto the canvas will exactly match colors obtained through the getImageData()
method.
The toDataURL() method
must not include color space information in the resource
returned. Where the output format allows it, the color of pixels in
resources created by toDataURL() must match those
returned by the getImageData()
method.
In user agents that support CSS, the color space used by a
canvas element must match the color space used for
processing any colors for that element in CSS.
The gamma correction and color space information of images must
be handled in such a way that an image rendered directly using an
img element would use the same colors as one painted on
a canvas element that is then itself
rendered. Furthermore, the rendering of images that have no color
correction information (such as those returned by the toDataURL() method) must be
rendered with no color correction.
Thus, in the 2D context, calling the drawImage() method to render
the output of the toDataURL() method to the
canvas, given the appropriate dimensions, has no visible effect.
canvas elementsInformation leakage can occur if scripts from one origin can access information (e.g. read pixels) from images from another origin (one that isn't the same).
To mitigate this, canvas elements are defined to
have a flag indicating whether they are origin-clean. All
canvas elements must start with their
origin-clean set to true. The flag must be set to false if
any of the following actions occur:
The element's 2D context's drawImage() method is
called with an HTMLImageElement or an
HTMLVideoElement whose origin is not the
same as that of the
Document object that owns the canvas
element.
The element's 2D context's drawImage() method is
called with an HTMLCanvasElement whose
origin-clean flag is false.
The element's 2D context's fillStyle attribute is set
to a CanvasPattern object that was created from an
HTMLImageElement or an HTMLVideoElement
whose origin was not the same as that of the Document object
that owns the canvas element when the pattern was
created.
The element's 2D context's fillStyle attribute is set
to a CanvasPattern object that was created from an
HTMLCanvasElement whose origin-clean flag was
false when the pattern was created.
The element's 2D context's strokeStyle attribute is
set to a CanvasPattern object that was created from an
HTMLImageElement or an HTMLVideoElement
whose origin was not the same as that of the Document object
that owns the canvas element when the pattern was
created.
The element's 2D context's strokeStyle attribute is
set to a CanvasPattern object that was created from an
HTMLCanvasElement whose origin-clean flag was
false when the pattern was created.
Whenever the toDataURL() method of a
canvas element whose origin-clean flag is set to
false is called, the method must raise a SECURITY_ERR
exception.
Whenever the getImageData() method of
the 2D context of a canvas element whose
origin-clean flag is set to false is called with otherwise
correct arguments, the method must raise a SECURITY_ERR
exception.
Even resetting the canvas state by changing its
width or height attributes doesn't reset
the origin-clean flag.
map elementnameinterface HTMLMapElement : HTMLElement {
attribute DOMString name;
readonly attribute HTMLCollection areas;
readonly attribute HTMLCollection images;
};
The map element, in conjunction with any
area element descendants, defines an image
map. The element represents its children.
The name attribute
gives the map a name so that it can be referenced. The attribute
must be present and must have a non-empty value with no space characters. The value of the
name attribute must not be a
compatibility-caseless
match for the value of the name
attribute of another map element in the same
document. If the id attribute is also
specified, both attributes must have the same value.
areasReturns an HTMLCollection of the area elements in the map.
imagesReturns an HTMLCollection of the img and object elements that use the map.
The areas attribute
must return an HTMLCollection rooted at the
map element, whose filter matches only
area elements.
The images
attribute must return an HTMLCollection rooted at the
Document node, whose filter matches only
img and object elements that are
associated with this map element according to the
image map processing model.
The IDL attribute name must
reflect the content attribute of the same name.
area elementmap element ancestor.altcoordsshapehreftargetpingrelmediahreflangtypeinterface HTMLAreaElement : HTMLElement {
attribute DOMString alt;
attribute DOMString coords;
attribute DOMString shape;
stringifier attribute DOMString href;
attribute DOMString target;
attribute DOMString ping;
attribute DOMString rel;
readonly attribute DOMTokenList relList;
attribute DOMString media;
attribute DOMString hreflang;
attribute DOMString type;
// URL decomposition IDL attributes
attribute DOMString protocol;
attribute DOMString host;
attribute DOMString hostname;
attribute DOMString port;
attribute DOMString pathname;
attribute DOMString search;
attribute DOMString hash;
};
The area element represents either a
hyperlink with some text and a corresponding area on an image
map, or a dead area on an image map.
If the area element has an href attribute, then the
area element represents a hyperlink. In
this case, the alt
attribute must be present. It specifies the text of the
hyperlink. Its value must be text that, when presented with the
texts specified for the other hyperlinks of the image
map, and with the alternative text of the image, but without
the image itself, provides the user with the same kind of choice as
the hyperlink would when used without its text but with its shape
applied to the image. The alt
attribute may be left blank if there is another area
element in the same image map that points to the same
resource and has a non-blank alt
attribute.
If the area element has no href attribute, then the area
represented by the element cannot be selected, and the alt attribute must be omitted.
In both cases, the shape and
coords attributes specify the
area.
The shape
attribute is an enumerated attribute. The following
table lists the keywords defined for this attribute. The states
given in the first cell of the rows with keywords give the states to
which those keywords map. Some of the keywords
are non-conforming, as noted in the last column.
| State | Keywords | Notes |
|---|---|---|
| Circle state | circle
| |
circ
| Non-conforming | |
| Default state | default
| |
| Polygon state | poly
| |
polygon
| Non-conforming | |
| Rectangle state | rect
| |
rectangle
| Non-conforming |
The attribute may be omitted. The missing value default is the rectangle state.
The coords
attribute must, if specified, contain a valid list of
integers. This attribute gives the coordinates for the shape
described by the shape
attribute. The processing for this attribute is
described as part of the image map processing
model.
In the circle state,
area elements must have a coords attribute present, with three
integers, the last of which must be non-negative. The first integer
must be the distance in CSS pixels from the left edge of the image
to the center of the circle, the second integer must be the distance
in CSS pixels from the top edge of the image to the center of the
circle, and the third integer must be the radius of the circle,
again in CSS pixels.
In the default state
state, area elements must not have a coords attribute. (The area is the
whole image.)
In the polygon state,
area elements must have a coords attribute with at least six
integers, and the number of integers must be even. Each pair of
integers must represent a coordinate given as the distances from the
left and the top of the image in CSS pixels respectively, and all
the coordinates together must represent the points of the polygon,
in order.
In the rectangle state,
area elements must have a coords attribute with exactly four
integers, the first of which must be less than the third, and the
second of which must be less than the fourth. The four points must
represent, respectively, the distance from the left edge of the
image to the left side of the rectangle, the distance from the
top edge to the top side, the distance from the left edge to the
right side, and the distance from the top edge to the bottom side,
all in CSS pixels.
When user agents allow users to follow hyperlinks created using the
area element, as described in the next section, the
href,
target
and ping
attributes decide how the
link is followed. The rel,
media, hreflang, and type attributes may be used to
indicate to the user the likely nature of the target resource before
the user follows the link.
The target,
ping,
rel, media, hreflang, and type attributes must be omitted
if the href attribute is
not present.
The activation behavior of area
elements is to run the following steps:
If the DOMActivate
event in question is not trusted (i.e. a click() method call was the reason for the
event being dispatched), and the area element's target attribute is such that
applying the rules for choosing a browsing context given a
browsing context name, using the value of the target attribute as the
browsing context name, would result in there not being a chosen
browsing context, then raise an INVALID_ACCESS_ERR
exception and abort these steps.
area element, if any.The IDL attributes alt, coords, href, target,
ping,
rel, media, hreflang, and type, each must
reflect the respective content attributes of the same
name.
The IDL attribute shape must
reflect the shape
content attribute, limited to only known values.
The IDL attribute relList must
reflect the rel
content attribute.
The area element also supports the complement of
URL decomposition IDL attributes, protocol, host, port, hostname, pathname, search, and hash. These must follow the
rules given for URL decomposition IDL attributes, with the input being the result of resolving the element's href attribute relative to the
element, if there is such an attribute and resolving it is
successful, or the empty string otherwise; and the common setter action being the
same as setting the element's href attribute to the new output
value.
An image map allows geometric areas on an image to be associated with hyperlinks.
An image, in the form of an img element or an
object element representing an image, may be associated
with an image map (in the form of a map element) by
specifying a usemap attribute on
the img or object element. The usemap attribute, if specified,
must be a valid hash-name reference to a
map element.
Consider an image that looks as follows:

If we wanted just the colored areas to be clickable, we could do it as follows:
<p>
Please select a shape:
<img src="shapes.png" usemap="#shapes"
alt="Four shapes are available: a red hollow box, a green circle, a blue triangle, and a yellow four-pointed star.">
<map name="shapes">
<area shape=rect coords="50,50,100,100"> <!-- the hole in the red box -->
<area shape=rect coords="25,25,125,125" href="red.html" alt="Red box.">
<area shape=circle coords="200,75,50" href="green.html" alt="Green circle.">
<area shape=poly coords="325,25,262,125,388,125" href="blue.html" alt="Blue triangle.">
<area shape=poly coords="450,25,435,60,400,75,435,90,450,125,465,90,500,75,465,60"
href="yellow.html" alt="Yellow star.">
</map>
</p>
If an img element or an object element
representing an image has a usemap attribute specified,
user agents must process it as follows:
First, rules for parsing a hash-name reference
to a map element must be followed. This will return
either an element (the map) or null.
If that returned null, then abort these steps. The image is not associated with an image map after all.
Otherwise, the user agent must collect all the
area elements that are descendants of the map. Let those be the areas.
Having obtained the list of area elements that form
the image map (the areas), interactive user
agents must process the list in one of two ways.
If the user agent intends to show the text that the
img element represents, then it must use the following
steps.
In user agents that do not support images, or that
have images disabled, object elements cannot represent
images, and thus this section never applies (the fallback
content is shown instead). The following steps therefore only
apply to img elements.
Remove all the area elements in areas that have no href attribute.
Remove all the area elements in areas that have no alt attribute, or whose alt attribute's value is the empty
string, if there is another area element in
areas with the same value in the href attribute and with a
non-empty alt attribute.
Each remaining area element in areas represents a hyperlink. Those
hyperlinks should all be made available to the user in a manner
associated with the text of the img.
In this context, user agents may represent area and
img elements with no specified alt attributes, or whose alt
attributes are the empty string or some other non-visible text, in
a user-agent-defined fashion intended to indicate the lack of
suitable author-provided text.
If the user agent intends to show the image and allow interaction
with the image to select hyperlinks, then the image must be
associated with a set of layered shapes, taken from the
area elements in areas, in reverse
tree order (so the last specified area element in the
map is the bottom-most shape, and the first
element in the map, in tree order, is the
top-most shape).
Each area element in areas must
be processed as follows to obtain a shape to layer onto the
image:
Find the state that the element's shape attribute represents.
Use the rules for parsing a list of integers to
parse the element's coords
attribute, if it is present, and let the result be the coords list. If the attribute is absent, let the
coords list be the empty list.
If the number of items in the coords
list is less than the minimum number given for the
area element's current state, as per the following
table, then the shape is empty; abort these steps.
| State | Minimum number of items |
|---|---|
| Circle state | 3 |
| Default state | 0 |
| Polygon state | 6 |
| Rectangle state | 4 |
Check for excess items in the coords
list as per the entry in the following list corresponding to the
shape attribute's state:
If the shape attribute
represents the rectangle
state, and the first number in the list is numerically less
than the third number in the list, then swap those two numbers
around.
If the shape attribute
represents the rectangle
state, and the second number in the list is numerically less
than the fourth number in the list, then swap those two numbers
around.
If the shape attribute
represents the circle
state, and the third number in the list is less than or
equal to zero, then the shape is empty; abort these steps.
Now, the shape represented by the element is the one
described for the entry in the list below corresponding to the
state of the shape
attribute:
Let x be the first number in coords, y be the second number, and r be the third number.
The shape is a circle whose center is x CSS pixels from the left edge of the image and x CSS pixels from the top edge of the image, and whose radius is r pixels.
The shape is a rectangle that exactly covers the entire image.
Let xi be the (2i)th entry in coords, and yi be the (2i+1)th entry in coords (the first entry in coords being the one with index 0).
Let the coordinates be (xi, yi), interpreted in CSS pixels measured from the top left of the image, for all integer values of i from 0 to (N/2)-1, where N is the number of items in coords.
The shape is a polygon whose vertices are given by the coordinates, and whose interior is established using the even-odd rule. [GRAPHICS]
Let x1 be the first number in coords, y1 be the second number, x2 be the third number, and y2 be the fourth number.
The shape is a rectangle whose top-left corner is given by the coordinate (x1, y1) and whose bottom right corner is given by the coordinate (x2, y2), those coordinates being interpreted as CSS pixels from the top left corner of the image.
For historical reasons, the coordinates must be interpreted
relative to the displayed image, even if it stretched
using CSS or the image element's width and
height attributes.
Mouse clicks on an image associated with a set of layered shapes
per the above algorithm must be dispatched to the top-most shape
covering the point that the pointing device indicated (if any), and
then, must be dispatched again (with a new Event
object) to the image element itself. User agents may also allow
individual area elements representing hyperlinks to be selected and activated
(e.g. using a keyboard); events from this are not also propagated to
the image.
Because a map element (and its
area elements) can be associated with multiple
img and object elements, it is possible
for an area element to correspond to multiple focusable
areas of the document.
Image maps are live; if the DOM is mutated, then the user agent must act as if it had rerun the algorithms for image maps.
The math element from the MathML
namespace falls into the embedded content,
phrasing content, and flow content
categories for the purposes of the content models in this
specification.
User agents must handle text other than inter-element
whitespace found in MathML elements whose content models do
not allow straight text by pretending for the purposes of MathML
content models, layout, and rendering that that text is actually
wrapped in an mtext element in the
MathML namespace. (Such text is not, however,
conforming.)
User agents must act as if any MathML element whose contents does
not match the element's content model was replaced, for the purposes
of MathML layout and rendering, by an merror
element in the MathML namespace containing some
appropriate error message.
To enable authors to use MathML tools that only accept MathML in its XML form, interactive HTML user agents are encouraged to provide a way to export any MathML fragment as an XML namespace-well-formed XML fragment.
The semantics of MathML elements are defined by the MathML specification and other relevant specifications. [MATHML]
Here is an example of the use of MathML in an HTML document:
<!DOCTYPE html>
<html>
<head>
<title>The quadratic formula</title>
</head>
<body>
<h1>The quadratic formula</h1>
<p>
<math>
<mi>x</mi>
<mo>=</mo>
<mfrac>
<mrow>
<mo form="prefix">−</mo> <mi>b</mi>
<mo>±</mo>
<msqrt>
<msup> <mi>b</mi> <mn>2</mn> </msup>
<mo>−</mo>
<mn>4</mn> <mo></mo> <mi>a</mi> <mo></mo> <mi>c</mi>
</msqrt>
</mrow>
<mrow>
<mn>2</mn> <mo></mo> <mi>a</mi>
</mrow>
</mfrac>
</math>
</p>
</body>
</html>
The svg element from the SVG
namespace falls into the embedded content,
phrasing content, and flow content
categories for the purposes of the content models in this
specification.
To enable authors to use SVG tools that only accept SVG in its XML form, interactive HTML user agents are encouraged to provide a way to export any SVG fragment as an XML namespace-well-formed XML fragment.
When the SVG foreignObject element contains elements
from the HTML namespace, such elements must all be
flow content. [SVG]
The content model for title elements in the
SVG namespace inside HTML documents is
phrasing content. (This further constrains the
requirements given in the SVG specification.)
The semantics of SVG elements are defined by the SVG specification and other relevant specifications. [SVG]
The SVG specification includes requirements regarding the
handling of elements in the DOM that are not in the SVG namespace,
that are in SVG fragments, and that are not included in a
foreignObject element. This specification does
not define any processing for elements in SVG fragments that are not
in the HTML namespace; they are considered neither conforming nor
non-conforming from the perspective of this specification.
Author requirements:
The width and height attributes on
img, iframe, embed,
object, video, and, when their type attribute is in the Image Button state,
input elements may be specified to give the dimensions
of the visual content of the element (the width and height
respectively, relative to the nominal direction of the output
medium), in CSS pixels. The attributes, if specified, must have
values that are valid
non-negative integers.
The specified dimensions given may differ from the dimensions specified in the resource itself, since the resource may have a resolution that differs from the CSS pixel resolution. (On screens, CSS pixels have a resolution of 96ppi, but in general the CSS pixel resolution depends on the reading distance.) If both attributes are specified, then one of the following statements must be true:
The target ratio is the ratio of the
intrinsic width to the intrinsic height in the resource. The specified width and specified
height are the values of the width and height attributes respectively.
The two attributes must be omitted if the resource in question does not have both an intrinsic width and an intrinsic height.
If the two attributes are both zero, it indicates that the element is not intended for the user (e.g. it might be a part of a service to count page views).
The dimension attributes are not intended to be used to stretch the image.
User agent requirements: User agents are expected to use these attributes as hints for the rendering.
The width and height IDL attributes on
the iframe, embed, object,
and video elements must reflect the
respective content attributes of the same name.
table elementcaption element,
followed by either zero or more colgroup elements,
followed optionally by a thead element, followed
optionally by a tfoot element, followed by either zero
or more tbody elements or one or more tr
elements, followed optionally by a tfoot element (but
there can only be one tfoot element child in
total).summary (but see prose)interface HTMLTableElement : HTMLElement {
attribute HTMLTableCaptionElement caption;
HTMLElement createCaption();
void deleteCaption();
attribute HTMLTableSectionElement tHead;
HTMLElement createTHead();
void deleteTHead();
attribute HTMLTableSectionElement tFoot;
HTMLElement createTFoot();
void deleteTFoot();
readonly attribute HTMLCollection tBodies;
HTMLElement createTBody();
readonly attribute HTMLCollection rows;
HTMLElement insertRow(in optional long index);
void deleteRow(in long index);
attribute DOMString summary;
};
The table element represents data with
more than one dimension, in the form of a table.
The table element takes part in the table
model.
Tables must not be used as layout aids. Historically, some Web authors have misused tables in HTML as a way to control their page layout. This usage is non-conforming, because tools attempting to extract tabular data from such documents would obtain very confusing results. In particular, users of accessibility tools like screen readers are likely to find it very difficult to navigate pages with tables used for layout.
There are a variety of alternatives to using HTML tables for layout, primarily using CSS positioning and the CSS table model.
User agents that do table analysis on arbitrary content are encouraged to find heuristics to determine which tables actually contain data and which are merely being used for layout. This specification does not define a precise heuristic.
Tables have rows and columns given by their descendants. A table must not have an empty row or column, as described in the description of the table model.
For tables that consist of more than just a grid of cells with headers in the first row and headers in the first column, and for any table in general where the reader might have difficulty understanding the content, authors should include explanatory information introducing the table. This information is useful for all users, but is especially useful for users who cannot see the table, e.g. users of screen readers.
Such explanatory information should introduce the purpose of the table, outline its basic cell structure, highlight any trends or patterns, and generally teach the user how to use the table.
For instance, the following table:
| Negative | Characteristic | Positive |
|---|---|---|
| Sad | Mood | Happy |
| Failing | Grade | Passing |
...might benefit from a description explaining the way the table is laid out, something like "Characteristics are given in the second column, with the negative side in the left column and the positive side in the right column".
There are a variety of ways to include this information, such as:
<p>In the following table, characteristics are given in the second column, with the negative side in the left column and the positive side in the right column.</p> <table> <caption>Characteristics with positive and negative sides</caption> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table>
caption<table> <caption> <strong>Characteristics with positive and negative sides.</strong> <p>Characteristics are given in the second column, with the negative side in the left column and the positive side in the right column.</p> </caption> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table>
caption, in a details element<table> <caption> <strong>Characteristics with positive and negative sides.</strong> <details> <summary>Help</summary> <p>Characteristics are given in the second column, with the negative side in the left column and the positive side in the right column.</p> </details> </caption> <thead> <tr> <th id="n"> Negative <th> Characteristic <th> Positive <tbody> <tr> <td headers="n r1"> Sad <th id="r1"> Mood <td> Happy <tr> <td headers="n r2"> Failing <th id="r2"> Grade <td> Passing </table>
figure<figure>
<figcaption>Characteristics with positive and negative sides</figcaption>
<p>Characteristics are given in the second column, with the
negative side in the left column and the positive side in the right
column.</p>
<table>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id="r1"> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id="r2"> Grade
<td> Passing
</table>
</figure>figure's figcaption<figure>
<figcaption>
<strong>Characteristics with positive and negative sides</strong>
<p>Characteristics are given in the second column, with the
negative side in the left column and the positive side in the right
column.</p>
</figcaption>
<table>
<thead>
<tr>
<th id="n"> Negative
<th> Characteristic
<th> Positive
<tbody>
<tr>
<td headers="n r1"> Sad
<th id="r1"> Mood
<td> Happy
<tr>
<td headers="n r2"> Failing
<th id="r2"> Grade
<td> Passing
</table>
</figure>Authors may also use other techniques, or combinations of the above techniques, as appropriate.
The best option, of course, rather than writing a description explaining the way the table is laid out, is to adjust the table such that no explanation is needed.
In the case of the table used in the examples above, a simple
rearrangement of the table so that the headers are on the top and
left sides removes the need for an explanation as well as removing
the need for the use of headers attributes:
<table> <caption>Characteristics with positive and negative sides</caption> <thead> <tr> <th> Characteristic <th> Negative <th> Positive <tbody> <tr> <th> Mood <td> Sad <td> Happy <tr> <th> Grade <td> Failing <td> Passing </table>
The summary
attribute on table elements was suggested in earlier
versions of the language as a technique for providing explanatory
text for complex tables for users of screen readers. One of the techniques described above should be used
instead.
In particular, authors are encouraged to consider
whether their explanatory text for tables is likely to be useful to
the visually impaired: if their text would not be useful, then it is
best to not include a summary attribute. Similarly, if
their explanatory text could help someone who is not visually
impaired, e.g. someone who is seeing the table for the first time,
then the text would be more useful before the table or in the
caption. For example, describing the conclusions of the
data in a table is useful to everyone; explaining how to read the
table, if not obvious from the headers alone, is useful to everyone;
describing the structure of the table, if it is easy to grasp
visually, may not be useful to everyone, but it might also not be
useful to users who can quickly navigate the table with an
accessibility tool.
If a table element has a summary attribute, the user agent
may report the contents of that attribute to the user.
caption [ = value ]Returns the table's caption element.
Can be set, to replace the caption element. If the
new value is not a caption element, throws a
HIERARCHY_REQUEST_ERR exception.
createCaption()Ensures the table has a caption element, and returns it.
deleteCaption()Ensures the table does not have a caption element.
tHead [ = value ]Returns the table's thead element.
Can be set, to replace the thead element. If the
new value is not a thead element, throws a
HIERARCHY_REQUEST_ERR exception.
createTHead()Ensures the table has a thead element, and returns it.
deleteTHead()Ensures the table does not have a thead element.
tFoot [ = value ]Returns the table's tfoot element.
Can be set, to replace the tfoot element. If the
new value is not a tfoot element, throws a
HIERARCHY_REQUEST_ERR exception.
createTFoot()Ensures the table has a tfoot element, and returns it.
deleteTFoot()Ensures the table does not have a tfoot element.
tBodiesReturns an HTMLCollection of the tbody elements of the table.
createTBody()Creates a tbody element, inserts it into the table, and returns it.
rowsReturns an HTMLCollection of the tr elements of the table.
insertRow(index)Creates a tr element, along with a tbody if required, inserts them into the table at the position given by the argument, and returns the tr.
The position is relative to the rows in the table. The index −1 is equivalent to inserting at the end of the table.
If the given position is less than −1 or greater than the number of rows, throws an INDEX_SIZE_ERR exception.
deleteRow(index)Removes the tr element with the given position in the table.
The position is relative to the rows in the table. The index −1 is equivalent to deleting the last row of the table.
If the given position is less than −1 or greater than the index of the last row, or if there are no rows, throws an INDEX_SIZE_ERR exception.
The caption IDL
attribute must return, on getting, the first caption
element child of the table element, if any, or null
otherwise. On setting, if the new value is a caption
element, the first caption element child of the
table element, if any, must be removed, and the new
value must be inserted as the first node of the table
element. If the new value is not a caption element,
then a HIERARCHY_REQUEST_ERR DOM exception must be
raised instead.
The createCaption()
method must return the first caption element child of
the table element, if any; otherwise a new
caption element must be created, inserted as the first
node of the table element, and then returned.
The deleteCaption()
method must remove the first caption element child of
the table element, if any.
The tHead IDL
attribute must return, on getting, the first thead
element child of the table element, if any, or null
otherwise. On setting, if the new value is a thead
element, the first thead element child of the
table element, if any, must be removed, and the new
value must be inserted immediately before the first element in the
table element that is neither a caption
element nor a colgroup element, if any, or at the end
of the table if there are no such elements. If the new value is not
a thead element, then a
HIERARCHY_REQUEST_ERR DOM exception must be raised
instead.
The createTHead()
method must return the first thead element child of the
table element, if any; otherwise a new
thead element must be created and inserted immediately
before the first element in the table element that is
neither a caption element nor a colgroup
element, if any, or at the end of the table if there are no such
elements, and then that new element must be returned.
The deleteTHead()
method must remove the first thead element child of the
table element, if any.
The tFoot IDL
attribute must return, on getting, the first tfoot
element child of the table element, if any, or null
otherwise. On setting, if the new value is a tfoot
element, the first tfoot element child of the
table element, if any, must be removed, and the new
value must be inserted immediately before the first element in the
table element that is neither a caption
element, a colgroup element, nor a thead
element, if any, or at the end of the table if there are no such
elements. If the new value is not a tfoot element, then
a HIERARCHY_REQUEST_ERR DOM exception must be raised
instead.
The createTFoot()
method must return the first tfoot element child of the
table element, if any; otherwise a new
tfoot element must be created and inserted immediately
before the first element in the table element that is
neither a caption element, a colgroup
element, nor a thead element, if any, or at the end of
the table if there are no such elements, and then that new element
must be returned.
The deleteTFoot()
method must remove the first tfoot element child of the
table element, if any.
The tBodies
attribute must return an HTMLCollection rooted at the
table node, whose filter matches only
tbody elements that are children of the
table element.
The createTBody()
method must create a new tbody element, insert it
immediately after the last tbody element in the
table element, if any, or at the end of the
table element if the table element has no
tbody element children, and then must return the new
tbody element.
The rows attribute
must return an HTMLCollection rooted at the
table node, whose filter matches only tr
elements that are either children of the table element,
or children of thead, tbody, or
tfoot elements that are themselves children of the
table element. The elements in the collection must be
ordered such that those elements whose parent is a
thead are included first, in tree order, followed by
those elements whose parent is either a table or
tbody element, again in tree order, followed finally by
those elements whose parent is a tfoot element, still
in tree order.
The behavior of the insertRow(index) method depends on the state of
the table. When it is called, the method must act as required by the
first item in the following list of conditions that describes the
state of the table and the index argument:
rows
collection:INDEX_SIZE_ERR
exception.rows collection has
zero elements in it, and the table has no
tbody elements in it:tbody element, then
create a tr element, then append the tr
element to the tbody element, then append the
tbody element to the table element, and
finally return the tr element.rows collection has
zero elements in it:tr element, append it to
the last tbody element in the table, and return the
tr element.rows collection:tr element, and append it
to the parent of the last tr element in the rows collection. Then, the newly
created tr element must be returned.tr element, insert it
immediately before the indexth tr
element in the rows collection,
in the same parent, and finally must return the newly created
tr element.When the deleteRow(index) method is called, the user agent
must run the following steps:
If index is equal to −1, then
index must be set to the number if items in the
rows collection, minus
one.
Now, if index is less than zero, or
greater than or equal to the number of elements in the rows collection, the method must
instead raise an INDEX_SIZE_ERR exception, and these
steps must be aborted.
Otherwise, the method must remove the indexth element in the rows collection from its parent.
The summary IDL
attribute must reflect the content attribute of the
same name.
caption elementtable element.table elements.interface HTMLTableCaptionElement : HTMLElement {};
The caption element represents the title of the
table that is its parent, if it has a parent and that
is a table element.
The caption element takes part in the table
model.
When a table element is the only content in a
figure element other than the figcaption,
the caption element should be omitted in favor of the
figcaption.
A caption can introduce context for a table, making it significantly easier to understand.
Consider, for instance, the following table:
| 1 | 2 | 3 | 4 | 5 | 6 | |
|---|---|---|---|---|---|---|
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| 2 | 3 | 4 | 5 | 6 | 7 | 8 |
| 3 | 4 | 5 | 6 | 7 | 8 | 9 |
| 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| 6 | 7 | 8 | 9 | 10 | 11 | 12 |
In the abstract, this table is not clear. However, with a caption giving the table's number (for reference in the main prose) and explaining its use, it makes more sense:
<caption> <p>Table 1. <p>This table shows the total score obtained from rolling two six-sided dice. The first row represents the value of the first die, the first column the value of the second die. The total is given in the cell that corresponds to the values of the two dice. </caption>
This provides the user with more context:
| 1 | 2 | 3 | 4 | 5 | 6 | |
|---|---|---|---|---|---|---|
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| 2 | 3 | 4 | 5 | 6 | 7 | 8 |
| 3 | 4 | 5 | 6 | 7 | 8 | 9 |
| 4 | 5 | 6 | 7 | 8 | 9 | 10 |
| 5 | 6 | 7 | 8 | 9 | 10 | 11 |
| 6 | 7 | 8 | 9 | 10 | 11 | 12 |
colgroup elementtable element, after any
caption elements and before any thead,
tbody, tfoot, and tr
elements.span attribute is present: Empty.span attribute is absent: Zero or more col elements.spaninterface HTMLTableColElement : HTMLElement {
attribute unsigned long span;
};
The colgroup element represents a group of one or more columns in the table that
is its parent, if it has a parent and that is a table
element.
If the colgroup element contains no col
elements, then the element may have a span content attribute
specified, whose value must be a valid non-negative
integer greater than zero.
The colgroup element and its span attribute take part in the
table model.
The span IDL
attribute must reflect the content attribute of the
same name. The value must be limited to only non-negative
numbers greater than zero.
col elementcolgroup element that doesn't have
a span attribute.spanHTMLTableColElement, same as for
colgroup elements. This interface defines one member,
span.
If a col element has a parent and that is a
colgroup element that itself has a parent that is a
table element, then the col element
represents one or more columns in the column group represented by that
colgroup.
The element may have a span content attribute
specified, whose value must be a valid non-negative
integer greater than zero.
The col element and its span attribute take part in the
table model.
The span IDL
attribute must reflect the content attribute of the
same name. The value must be limited to only non-negative
numbers greater than zero.
tbody elementtable element, after any
caption, colgroup, and
thead elements, but only if there are no
tr elements that are children of the
table element.tr elementsinterface HTMLTableSectionElement : HTMLElement {
readonly attribute HTMLCollection rows;
HTMLElement insertRow(in optional long index);
void deleteRow(in long index);
};
The HTMLTableSectionElement interface is also
used for thead and tfoot elements.
The tbody element represents a block of rows that consist of a body of data for
the parent table element, if the tbody
element has a parent and it is a table.
The tbody element takes part in the table
model.
rowsReturns an HTMLCollection of the tr elements of the table section.
insertRow( [ index ] )Creates a tr element, inserts it into the table section at the position given by the argument, and returns the tr.
The position is relative to the rows in the table section. The index −1, which is the default if the argument is omitted, is equivalent to inserting at the end of the table section.
If the given position is less than −1 or greater than the number of rows, throws an INDEX_SIZE_ERR exception.
deleteRow(index)Removes the tr element with the given position in the table section.
The position is relative to the rows in the table section. The index −1 is equivalent to deleting the last row of the table section.
If the given position is less than −1 or greater than the index of the last row, or if there are no rows, throws an INDEX_SIZE_ERR exception.
The rows attribute
must return an HTMLCollection rooted at the element,
whose filter matches only tr elements that are children
of the element.
The insertRow(index) method must, when invoked on an
element table section, act as follows:
If index is less than −1 or greater than the
number of elements in the rows
collection, the method must raise an INDEX_SIZE_ERR
exception.
If index is missing, equal to −1, or
equal to the number of items in the rows collection, the method must
create a tr element, append it to the element table section, and return the newly created
tr element.
Otherwise, the method must create a tr element,
insert it as a child of the table section
element, immediately before the indexth
tr element in the rows collection, and finally must
return the newly created tr element.
The deleteRow(index) method must remove the indexth element in the rows collection from its parent. If
index is less than zero or greater than or equal
to the number of elements in the rows collection, the method must
instead raise an INDEX_SIZE_ERR exception.
thead elementtable element, after any
caption, and colgroup
elements and before any tbody, tfoot, and
tr elements, but only if there are no other
thead elements that are children of the
table element.tr elementsHTMLTableSectionElement, as defined for
tbody elements.The thead element represents the block of rows that consist of the column labels
(headers) for the parent table element, if the
thead element has a parent and it is a
table.
The thead element takes part in the table
model.
tfoot elementtable element, after any
caption, colgroup, and thead
elements and before any tbody and tr
elements, but only if there are no other tfoot
elements that are children of the table element.table element, after any
caption, colgroup, thead,
tbody, and tr elements, but only if there
are no other tfoot elements that are children of the
table element.tr elementsHTMLTableSectionElement, as defined for
tbody elements.The tfoot element represents the block of rows that consist of the column summaries
(footers) for the parent table element, if the
tfoot element has a parent and it is a
table.
The tfoot element takes part in the table
model.
tr elementthead element.tbody element.tfoot element.table element, after any
caption, colgroup, and thead
elements, but only if there are no tbody elements that
are children of the table element.thead element: Zero or more th elementstd or th elementsinterface HTMLTableRowElement : HTMLElement {
readonly attribute long rowIndex;
readonly attribute long sectionRowIndex;
readonly attribute HTMLCollection cells;
HTMLElement insertCell(in optional long index);
void deleteCell(in long index);
};
The tr element represents a row of cells in a table.
The tr element takes part in the table
model.
rowIndexReturns the position of the row in the table's rows list.
Returns −1 if the element isn't in a table.
sectionRowIndexReturns the position of the row in the table section's rows list.
Returns −1 if the element isn't in a table section.
cellsReturns an HTMLCollection of the td and th elements of the row.
insertCell( [ index ] )Creates a td element, inserts it into the table
row at the position given by the argument, and returns the
td.
The position is relative to the cells in the row. The index −1, which is the default if the argument is omitted, is equivalent to inserting at the end of the row.
If the given position is less than −1 or greater than
the number of cells, throws an INDEX_SIZE_ERR
exception.
deleteCell(index)Removes the td or th element with the
given position in the row.
The position is relative to the cells in the row. The index −1 is equivalent to deleting the last cell of the row.
If the given position is less than −1 or greater than
the index of the last cell, or if there are no cells, throws an
INDEX_SIZE_ERR exception.
The rowIndex
attribute must, if the element has a parent table
element, or a parent tbody, thead, or
tfoot element and a grandparent
table element, return the index of the tr
element in that table element's rows collection. If there is no such
table element, then the attribute must return
−1.
The sectionRowIndex
attribute must, if the element has a parent table,
tbody, thead, or tfoot
element, return the index of the tr element in the
parent element's rows collection (for tables,
that's the HTMLTableElement.rows
collection; for table sections, that's the HTMLTableRowElement.rows
collection). If there is no such parent element, then the attribute
must return −1.
The cells attribute
must return an HTMLCollection rooted at the
tr element, whose filter matches only td
and th elements that are children of the
tr element.
The insertCell(index) method must act as follows:
If index is less than −1 or greater than the
number of elements in the cells
collection, the method must raise an INDEX_SIZE_ERR
exception.
If index is missing, equal to −1, or
equal to the number of items in cells collection, the method must create
a td element, append it to the tr element,
and return the newly created td element.
Otherwise, the method must create a td element,
insert it as a child of the tr element, immediately
before the indexth td or
th element in the cells collection, and finally must
return the newly created td element.
The deleteCell(index) method must remove the indexth element in the cells collection from its parent. If
index is less than zero or greater than or equal
to the number of elements in the cells collection, the method must
instead raise an INDEX_SIZE_ERR exception.
td elementtr element.colspanrowspanheadersinterface HTMLTableDataCellElement : HTMLTableCellElement {};
The td element represents a data cell in a table.
The td element and its colspan, rowspan, and headers attributes take part in the
table model.
th elementtr element.colspanrowspanheadersscopeinterface HTMLTableHeaderCellElement : HTMLTableCellElement {
attribute DOMString scope;
};
The th element represents a header cell in a table.
The th element may have a scope content attribute
specified. The scope attribute is
an enumerated attribute with five states, four of which
have explicit keywords:
row
keyword, which maps to the row statecol
keyword, which maps to the column staterowgroup keyword,
which maps to the row group stateth element's
scope attribute must not be in
the row group state if
the element is not anchored in a row group.colgroup keyword,
which maps to the column group stateth
element's scope attribute must
not be in the column
group state if the element is not anchored in a column group.The scope attribute's
missing value default is the auto state.
The th element and its colspan, rowspan, headers, and scope attributes take part in the
table model.
The scope IDL
attribute must reflect the content attribute of the
same name.
The following example shows how the scope attribute's rowgroup value affects which
data cells a header cell applies to.
Here is a markup fragment showing a table:
<table> <thead> <tr> <th> ID <th> Measurement <th> Average <th> Maximum <tbody> <tr> <td> <th scope=rowgroup> Cats <td> <td> <tr> <td> 93 <th> Legs <td> 3.5 <td> 4 <tr> <td> 10 <th> Tails <td> 1 <td> 1 <tbody> <tr> <td> <th scope=rowgroup> English speakers <td> <td> <tr> <td> 32 <th> Legs <td> 2.67 <td> 4 <tr> <td> 35 <th> Tails <td> 0.33 <td> 1 </table>
This would result in the following table:
| ID | Measurement | Average | Maximum |
|---|---|---|---|
| Cats | |||
| 93 | Legs | 3.5 | 4 |
| 10 | Tails | 1 | 1 |
| English speakers | |||
| 32 | Legs | 2.67 | 4 |
| 35 | Tails | 0.33 | 1 |
The headers in the first row all apply directly down to the rows in their column.
The headers with the explicit scope attributes apply to all the
cells in their row group other than the cells in the first column.
The remaining headers apply just to the cells to the right of them.

td and th elementsThe td and th elements may have a colspan content
attribute specified, whose value must be a valid non-negative
integer greater than zero.
The td and th elements may also have a
rowspan content
attribute specified, whose value must be a valid non-negative
integer.
These attributes give the number of columns and rows respectively that the cell is to span. These attributes must not be used to overlap cells, as described in the description of the table model.
The td and th element may have a headers content
attribute specified. The headers attribute, if specified,
must contain a string consisting of an unordered set of unique
space-separated tokens, each of which must have the value of
an ID of a th element taking part in the same table as the td or
th element (as defined by the
table model).
A th element with ID id is said
to be directly targeted by all td and
th elements in the same table that have headers attributes whose values
include as one of their tokens the ID id. A
th element A is said to be
targeted by a th or td element
B if either A is directly
targeted by B or if there exists an element
C that is itself targeted by the element
B and A is directly
targeted by C.
A th element must not be targeted by
itself.
The colspan, rowspan, and headers attributes take part in the
table model.
The td and th elements implement
interfaces that inherit from the HTMLTableCellElement
interface:
interface HTMLTableCellElement : HTMLElement {
attribute unsigned long colSpan;
attribute unsigned long rowSpan;
[PutForwards=value] readonly attribute DOMSettableTokenList headers;
readonly attribute long cellIndex;
};
cellIndexReturns the position of the cell in the row's cells list. This does not necessarily
correspond to the x-position of the cell in
the table, since earlier cells might cover multiple rows or
columns.
Returns 0 if the element isn't in a row.
The colSpan IDL
attribute must reflect the content attribute of the
same name. The value must be limited to only non-negative
numbers greater than zero.
The rowSpan IDL
attribute must reflect the content attribute of the
same name. Its default value, which must be used if parsing the
attribute as a non-negative integer returns an error, is 1.
The headers IDL
attribute must reflect the content attribute of the
same name.
The cellIndex
IDL attribute must, if the element has a parent tr
element, return the index of the cell's element in the parent
element's cells collection. If
there is no such parent element, then the attribute must return
0.
The various table elements and their content attributes together define the table model.
A table consists of cells
aligned on a two-dimensional grid of slots with coordinates (x, y). The grid is finite, and is
either empty or has one or more slots. If the grid has one or more
slots, then the x coordinates are always in the
range 0 ≤ x < xwidth, and the y
coordinates are always in the range 0 ≤ y < yheight. If one or both of xwidth and yheight are zero, then the table is empty (has
no slots). Tables correspond to table elements.
A cell is a set of slots anchored
at a slot (cellx, celly), and with a particular
width and height such that
the cell covers all the slots with coordinates (x, y) where cellx ≤ x < cellx+width and
celly ≤ y < celly+height. Cells can
either be data cells or header cells. Data cells
correspond to td elements, and header cells correspond
to th elements. Cells of both types can have zero or
more associated header cells.
It is possible, in certain error cases, for two cells to occupy the same slot.
A row is a complete set of slots
from x=0 to x=xwidth-1, for a particular value of y. Rows correspond to tr elements.
A column is a complete set of
slots from y=0 to y=yheight-1, for a particular value of x. Columns can correspond to col
elements, but in the absence of col elements are
implied.
A row group is a set of
rows anchored at a slot (0, groupy) with a particular height such that the row group covers all the slots
with coordinates (x, y)
where 0 ≤ x < xwidth and groupy ≤ y < groupy+height. Row groups
correspond to tbody, thead, and
tfoot elements. Not every row is necessarily in a row
group.
A column group is a set
of columns anchored at a slot
(groupx, 0) with a
particular width such that the column group
covers all the slots with coordinates (x, y) where groupx ≤ x < groupx+width and
0 ≤ y < yheight. Column groups
correspond to colgroup elements. Not every column is
necessarily in a column group.
Row groups cannot overlap each other. Similarly, column groups cannot overlap each other.
A cell cannot cover slots that are from two or more row groups. It is, however, possible for a cell to be in multiple column groups. All the slots that form part of one cell are part of zero or one row groups and zero or more column groups.
In addition to cells, columns, rows, row
groups, and column
groups, tables can have a
caption element associated with them. This gives the
table a heading, or legend.
A table model error is an error with the data
represented by table elements and their
descendants. Documents must not have table model errors.
To determine which elements correspond to which slots in a table associated with a
table element, to determine the dimensions of the table
(xwidth and yheight), and to determine if
there are any table model
errors, user agents must use the following algorithm:
Let xwidth be zero.
Let yheight be zero.
Let pending tfoot elements be
a list of tfoot elements, initially empty.
Let the table be the table represented by the
table element. The xwidth and yheight variables give the
table's dimensions. The table is
initially empty.
If the table element has no children elements,
then return the table (which will be empty),
and abort these steps.
Associate the first caption element child of the
table element with the table. If
there are no such children, then it has no associated
caption element.
Let the current element be the first
element child of the table element.
If a step in this algorithm ever requires the current element to be advanced to the next child of the
table when there is no such next child, then
the user agent must jump to the step labeled end, near the
end of this algorithm.
While the current element is not one of the
following elements, advance the current element to the next child of the
table:
If the current element is a
colgroup, follow these substeps:
Column groups: Process the current element according to the appropriate case below:
col element childrenFollow these steps:
Let xstart have the value of xwidth.
Let the current column be the first
col element child of the colgroup
element.
Columns: If the current column
col element has a span attribute, then parse its
value using the rules for parsing non-negative
integers.
If the result of parsing the value is not an error or zero, then let span be that value.
Otherwise, if the col element has no span attribute, or if trying to
parse the attribute's value resulted in an error or zero,
then let span be 1.
Increase xwidth by span.
Let the last span columns in the
table correspond to the current
column col element.
If current column is not the last
col element child of the colgroup
element, then let the current column be
the next col element child of the
colgroup element, and return to the step
labeled columns.
Let all the last columns in the
table from x=xstart to x=xwidth-1 form a
new column group,
anchored at the slot (xstart, 0), with width xwidth-xstart,
corresponding to the colgroup element.
col element childrenIf the colgroup element has a span attribute, then parse
its value using the rules for parsing non-negative
integers.
If the result of parsing the value is not an error or zero, then let span be that value.
Otherwise, if the colgroup element has no
span attribute, or
if trying to parse the attribute's value resulted in an
error or zero, then let span be 1.
Increase xwidth by span.
Let the last span columns in the
table form a new column group, anchored
at the slot (xwidth-span,
0), with width span, corresponding to
the colgroup element.
While the current element is not one of
the following elements, advance the current element to the next child of the
table:
If the current element is a
colgroup element, jump to the step labeled
column groups above.
Let ycurrent be zero.
Let the list of downward-growing cells be an empty list.
Rows: While the current element is
not one of the following elements, advance the current element to the next child of the
table:
If the current element is a
tr, then run the algorithm for processing
rows, advance
the current element to the next child of the
table, and return to the step labeled
rows.
Run the algorithm for ending a row group.
If the current element is a
tfoot, then add that element to the list of pending tfoot elements, advance the current element to the next child of the
table, and return to the step labeled
rows.
The current element is either a
thead or a tbody.
Run the algorithm for processing row groups.
Return to the step labeled rows.
End: For each tfoot element in the list of
pending tfoot elements, in tree
order, run the algorithm for processing row
groups.
If there exists a row or column in the table containing only slots that do not have a cell anchored to them, then this is a table model error.
Return the table.
The algorithm for processing row groups, which is
invoked by the set of steps above for processing
thead, tbody, and tfoot
elements, is:
Let ystart have the value of yheight.
For each tr element that is a child of the element
being processed, in tree order, run the algorithm for
processing rows.
If yheight > ystart, then let all the last rows in the table from y=ystart to y=yheight-1 form a new row group, anchored at the slot with coordinate (0, ystart), with height yheight-ystart, corresponding to the element being processed.
Run the algorithm for ending a row group.
The algorithm for ending a row group, which is invoked by the set of steps above when starting and ending a block of rows, is:
While ycurrent is less than yheight, follow these steps:
Increase ycurrent by 1.
Empty the list of downward-growing cells.
The algorithm for processing rows, which is invoked by
the set of steps above for processing tr elements,
is:
If yheight is equal to ycurrent, then increase yheight by 1. (ycurrent is never greater than yheight.)
Let xcurrent be 0.
If the tr element being processed has no
td or th element children, then increase
ycurrent by 1, abort this
set of steps, and return to the algorithm above.
Let current cell be the first
td or th element in the tr
element being processed.
Cells: While xcurrent is less than xwidth and the slot with coordinate (xcurrent, ycurrent) already has a cell assigned to it, increase xcurrent by 1.
If xcurrent is equal to xwidth, increase xwidth by 1. (xcurrent is never greater than xwidth.)
If the current cell has a colspan attribute, then parse that
attribute's value, and let colspan be
the result.
If parsing that value failed, or returned zero, or if the attribute is absent, then let colspan be 1, instead.
If the current cell has a rowspan attribute, then parse that attribute's
value, and let rowspan be the
result.
If parsing that value failed or if the attribute is absent, then let rowspan be 1, instead.
If rowspan is zero, then let cell grows downward be true, and set rowspan to 1. Otherwise, let cell grows downward be false.
If xwidth < xcurrent+colspan, then let xwidth be xcurrent+colspan.
If yheight < ycurrent+rowspan, then let yheight be ycurrent+rowspan.
Let the slots with coordinates (x, y) such that xcurrent ≤ x < xcurrent+colspan and ycurrent ≤ y < ycurrent+rowspan be covered by a new cell c, anchored at (xcurrent, ycurrent), which has width colspan and height rowspan, corresponding to the current cell element.
If the current cell element is a
th element, let this new cell c
be a header cell; otherwise, let it be a data cell.
To establish which header cells apply to the current cell element, use the algorithm for assigning header cells described in the next section.
If any of the slots involved already had a cell covering them, then this is a table model error. Those slots now have two cells overlapping.
If cell grows downward is true, then add the tuple {c, xcurrent, colspan} to the list of downward-growing cells.
Increase xcurrent by colspan.
If current cell is the last td
or th element in the tr element being
processed, then increase ycurrent by 1, abort this set of steps, and
return to the algorithm above.
Let current cell be the next
td or th element in the tr
element being processed.
Return to the step labelled cells.
When the algorithms above require the user agent to run the algorithm for growing downward-growing cells, the user agent must, for each {cell, cellx, width} tuple in the list of downward-growing cells, if any, extend the cell cell so that it also covers the slots with coordinates (x, ycurrent), where cellx ≤ x < cellx+width.
Each cell can be assigned zero or more header cells. The algorithm for assigning header cells to a cell principal cell is as follows.
Let header list be an empty list of cells.
Let (principalx, principaly) be the coordinate of the slot to which the principal cell is anchored.
headers attribute specifiedTake the value of the principal cell's
headers attribute and
split it on
spaces, letting id list be the list
of tokens obtained.
For each token in the id list, if the
first element in the Document with an ID equal to
the token is a cell in the same table, and that cell is not the
principal cell, then add that cell to header list.
headers attribute specifiedLet principalwidth be the width of the principal cell.
Let principalheight be the height of the principal cell.
For each value of y from principaly to principaly+principalheight-1, run the internal algorithm for scanning and assigning header cells, with the principal cell, the header list, the initial coordinate (principalx,y), and the increments Δx=−1 and Δy=0.
For each value of x from principalx to principalx+principalwidth-1, run the internal algorithm for scanning and assigning header cells, with the principal cell, the header list, the initial coordinate (x,principaly), and the increments Δx=0 and Δy=−1.
If the principal cell is anchored in a row group, then add all header cells that are row group headers and are anchored in the same row group with an x-coordinate less than or equal to principalx+principalwidth-1 and a y-coordinate less than or equal to principaly+principalheight-1 to header list.
If the principal cell is anchored in a column group, then add all header cells that are column group headers and are anchored in the same column group with an x-coordinate less than or equal to principalx+principalwidth-1 and a y-coordinate less than or equal to principaly+principalheight-1 to header list.
Remove all the empty cells from the header list.
Remove any duplicates from the header list.
Remove principal cell from the header list if it is there.
Assign the headers in the header list to the principal cell.
The internal algorithm for scanning and assigning header cells, given a principal cell, a header list, an initial coordinate (initialx, initialy), and Δx and Δy increments, is as follows:
Let x equal initialx.
Let y equal initialy.
Let opaque headers be an empty list of cells.
Let in header block be true, and let headers from current header block be a list of cells containing just the principal cell.
Let in header block be false and let headers from current header block be an empty list of cells.
Loop: Increment x by Δx; increment y by Δy.
For each invocation of this algorithm, one of Δx and Δy will be −1, and the other will be 0.
If either x or y is less than 0, then abort this internal algorithm.
If there is no cell covering slot (x, y), or if there is more than one cell covering slot (x, y), return to the substep labeled loop.
Let current cell be the cell covering slot (x, y).
Set in header block to true.
Add current cell to headers from current header block.
Let blocked be false.
If there are any cells in the opaque headers list anchored with the same x-coordinate as the current cell, and with the same width as current cell, then let blocked be true.
If the current cell is not a column header, then let blocked be true.
If there are any cells in the opaque headers list anchored with the same y-coordinate as the current cell, and with the same height as current cell, then let blocked be true.
If the current cell is not a row header, then let blocked be true.
If blocked is false, then add the current cell to the headers list.
Set in header block to false. Add all the cells in headers from current header block to the opaque headers list, and empty the headers from current header block list.
Return to the step labeled loop.
A header cell anchored at the slot with coordinate (x, y) with width width and height height is said to be a column header if any of the following conditions are true:
scope attribute
is in the column state, orscope attribute
is in the auto state, and
there are no data cells in any of the cells covering slots with
y-coordinates y
.. y+height-1.A header cell anchored at the slot with coordinate (x, y) with width width and height height is said to be a row header if any of the following conditions are true:
scope attribute
is in the row state, orscope attribute
is in the auto state, the
cell is not a column header, and there are no data
cells in any of the cells covering slots with x-coordinates x .. x+width-1.A header cell is said to be a column group header if
its scope attribute is in the
column group state.
A header cell is said to be a row group header if
its scope attribute is in the
row group state.
A cell is said to be an empty cell if it contains no elements and its text content, if any, consists only of White_Space characters.
This section is non-normative.
The following shows how might one mark up the bottom part of table 45 of the Smithsonian physical tables, Volume 71:
<table> <caption>Specification values: <b>Steel</b>, <b>Castings</b>, Ann. A.S.T.M. A27-16, Class B;* P max. 0.06; S max. 0.05.</caption> <thead> <tr> <th rowspan=2>Grade.</th> <th rowspan=2>Yield Point.</th> <th colspan=2>Ultimate tensile strength</th> <th rowspan=2>Per cent elong. 50.8mm or 2 in.</th> <th rowspan=2>Per cent reduct. area.</th> </tr> <tr> <th>kg/mm<sup>2</sup></th> <th>lb/in<sup>2</sup></th> </tr> </thead> <tbody> <tr> <td>Hard</td> <td>0.45 ultimate</td> <td>56.2</td> <td>80,000</td> <td>15</td> <td>20</td> </tr> <tr> <td>Medium</td> <td>0.45 ultimate</td> <td>49.2</td> <td>70,000</td> <td>18</td> <td>25</td> </tr> <tr> <td>Soft</td> <td>0.45 ultimate</td> <td>42.2</td> <td>60,000</td> <td>22</td> <td>30</td> </tr> </tbody> </table>
This table could look like this:
| Grade. | Yield Point. | Ultimate tensile strength | Per cent elong. 50.8 mm or 2 in. | Per cent reduct. area. | |
|---|---|---|---|---|---|
| kg/mm2 | lb/in2 | ||||
| Hard | 0.45 ultimate | 56.2 | 80,000 | 15 | 20 |
| Medium | 0.45 ultimate | 49.2 | 70,000 | 18 | 25 |
| Soft | 0.45 ultimate | 42.2 | 60,000 | 22 | 30 |
The following shows how one might mark up the gross margin table on page 46 of Apple, Inc's 10-K filing for fiscal year 2008:
<table> <thead> <tr> <th> <th>2008 <th>2007 <th>2006 <tbody> <tr> <th>Net sales <td>$ 32,479 <td>$ 24,006 <td>$ 19,315 <tr> <th>Cost of sales <td> 21,334 <td> 15,852 <td> 13,717 <tbody> <tr> <th>Gross margin <td>$ 11,145 <td>$ 8,154 <td>$ 5,598 <tfoot> <tr> <th>Gross margin percentage <td>34.3% <td>34.0% <td>29.0% </table>
This table could look like this:
| 2008 | 2007 | 2006 | |
|---|---|---|---|
| Net sales | $ 32,479 | $ 24,006 | $ 19,315 |
| Cost of sales | 21,334 | 15,852 | 13,717 |
| Gross margin | $ 11,145 | $ 8,154 | $ 5,598 |
| Gross margin percentage | 34.3% | 34.0% | 29.0% |
The following shows how one might mark up the operating expenses table from lower on the same page of that document:
<table>
<colgroup> <col>
<colgroup> <col> <col> <col>
<thead>
<tr> <th> <th>2008 <th>2007 <th>2006
<tbody>
<tr> <th scope=rowgroup> Research and development
<td> $ 1,109 <td> $ 782 <td> $ 712
<tr> <th scope=row> Percentage of net sales
<td> 3.4% <td> 3.3% <td> 3.7%
<tbody>
<tr> <th scope=rowgroup> Selling, general, and administrative
<td> $ 3,761 <td> $ 2,963 <td> $ 2,433
<tr> <th scope=row> Percentage of net sales
<td> 11.6% <td> 12.3% <td> 12.6%
</table>
This table could look like this:
| 2008 | 2007 | 2006 | |
|---|---|---|---|
| Research and development | $ 1,109 | $ 782 | $ 712 |
| Percentage of net sales | 3.4% | 3.3% | 3.7% |
| Selling, general, and administrative | $ 3,761 | $ 2,963 | $ 2,433 |
| Percentage of net sales | 11.6% | 12.3% | 12.6% |
This section is non-normative.
Forms allow unscripted client-server interaction: given a form, a user can provide data, submit it to the server, and have the server act on it accordingly (e.g. returning the results of a search or calculation). The elements used in forms can also be used for user interaction with no associated submission mechanism, in conjunction with scripts.
Writing a form consists of several steps, which can be performed in any order: writing the user interface, implementing the server-side processing, and configuring the user interface to communicate with the server.
This section is non-normative.
For the purposes of this brief introduction, we will create a pizza ordering form.
Any form starts with a form element, inside which
are placed the controls. Most controls are represented by the
input element, which by default provides a one-line
text field. To label a control, the label element is
used; the label text and the control itself go inside the
label element. Each part of a form is considered a
paragraph, and is typically separated from other parts
using p elements. Putting this together, here is how
one might ask for the customer's name:
<form> <p><label>Customer name: <input></label></p> </form>
To let the user select the size of the pizza, we can use a set of
radio buttons. Radio buttons also use the input
element, this time with a type
attribute with the value radio. To make the radio
buttons work as a group, they are given a common name using the
name attribute. To group a batch
of controls together, such as, in this case, the radio buttons, one
can use the fieldset element. The title of such a group
of controls is given by the first element in the
fieldset, which has to be a legend
element.
<form> <p><label>Customer name: <input></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> </form>
Changes from the previous step are highlighted.
To pick toppings, we can use checkboxes. These use the
input element with a type attribute with the value checkbox:
<form> <p><label>Customer name: <input></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> </form>
The pizzeria for which this form is being written is always
making mistakes, so it needs a way to contact the customer. For this
purpose, we can use form controls specifically for telephone numbers
(input elements with their type attribute set to tel) and e-mail addresses
(input elements with their type attribute set to email):
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> </form>
We can use an input element with its type attribute set to time to ask for a delivery
time. Many of these form controls have attributes to control exactly
what values can be specified; in this case, three attributes of
particular interest are min,
max, and step. These set the minimum time, the
maximum time, and the interval between allowed values (in
seconds). This pizzeria only delivers between 11am and 9pm, and
doesn't promise anything better than 15 minute increments, which we
can mark up as follows:
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p> </form>
The textarea element can be used to provide a
free-form text field. In this instance, we are going to use it to
provide a space for the customer to give delivery instructions:
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p> <p><label>Delivery instructions: <textarea></textarea></label></p> </form>
Finally, to make the form submittable we use the
button element:
<form> <p><label>Customer name: <input></label></p> <p><label>Telephone: <input type=tel></label></p> <p><label>E-mail address: <input type=email></label></p> <fieldset> <legend> Pizza Size </legend> <p><label> <input type=radio name=size> Small </label></p> <p><label> <input type=radio name=size> Medium </label></p> <p><label> <input type=radio name=size> Large </label></p> </fieldset> <fieldset> <legend> Pizza Toppings </legend> <p><label> <input type=checkbox> Bacon </label></p> <p><label> <input type=checkbox> Extra Cheese </label></p> <p><label> <input type=checkbox> Onion </label></p> <p><label> <input type=checkbox> Mushroom </label></p> </fieldset> <p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900"></label></p> <p><label>Delivery instructions: <textarea></textarea></label></p> <p><button>Submit order</button><p> </form>
This section is non-normative.
The exact details for writing a server-side processor are out of
scope for this specification. For the purposes of this introduction,
we will assume that the script at https://pizza.example.com/order.cgi is configured to
accept submissions using the application/x-www-form-urlencoded
format, expecting the following parameters sent in an HTTP POST
body:
custnamecusttelcustemailsizesmall, medium, or largetoppingsbacon, cheese, onion, and mushroomdeliverycommentsThis section is non-normative.
Form submissions are exposed to servers in a variety of ways,
most commonly as HTTP GET or POST requests. To specify the exact
method used, the method
attribute is specified on the form element. This
doesn't specify how the form data is encoded, though; to specify
that, you use the enctype
attribute. You also have to specify the URL of the
service that will handle the submitted data, using the action attribute.
For each form control you want submitted, you then have to give a
name that will be used to refer to the data in the submission. We
already specified the name for the group of radio buttons; the same
attribute (name) also specifies
the submission name. Radio buttons can be distinguished from each
other in the submission by giving them different values, using the
value attribute.
Multiple controls can have the same name; for example, here we
give all the checkboxes the same name, and the server distinguishes
which checkbox was checked by seeing which values are submitted with
that name — like the radio buttons, they are also given unique
values with the value
attribute.
Given the settings in the previous section, this all becomes:
<form method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi">
<p><label>Customer name: <input name="custname"></label></p>
<p><label>Telephone: <input type=tel name="custtel"></label></p>
<p><label>E-mail address: <input type=email name="custemail"></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size value="small"> Small </label></p>
<p><label> <input type=radio name=size value="medium"> Medium </label></p>
<p><label> <input type=radio name=size value="large"> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p>
<p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p>
<p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p>
<p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery"></label></p>
<p><label>Delivery instructions: <textarea name="comments"></textarea></label></p>
<p><button>Submit order</button><p>
</form>
For example, if the customer entered "Denise Lawrence" as their name, "555-321-8642" as their telephone number, did not specify an e-mail address, asked for a medium-sized pizza, selected the Extra Cheese and Mushroom toppings, entered a delivery time of 7pm, and left the delivery instructions text field blank, the user agent would submit the following to the online Web service:
custname=Denise+Lawrence&custtel=555-321-8624&custemail=&size=medium&topping=cheese&topping=mushroom&delivery=19%3A00&comments=
This section is non-normative.
Forms can be annotated in such a way that the user agent will check the user's input before the form is submitted. The server still has to verify the input is valid (since hostile users can easily bypass the form validation), but it allows the user to avoid the wait incurred by having the server be the sole checker of the user's input.
The simplest annotation is the required attribute, which can be
specified on input elements to indicate that the form
is not to be submitted until a value is given. By adding this
attribute to the customer name and delivery time fields, we allow
the user agent to notify the user when the user submits the form
without filling in those fields:
<form method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi">
<p><label>Customer name: <input name="custname" required></label></p>
<p><label>Telephone: <input type=tel name="custtel"></label></p>
<p><label>E-mail address: <input type=email name="custemail"></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size value="small"> Small </label></p>
<p><label> <input type=radio name=size value="medium"> Medium </label></p>
<p><label> <input type=radio name=size value="large"> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p>
<p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p>
<p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p>
<p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery" required></label></p>
<p><label>Delivery instructions: <textarea name="comments"></textarea></label></p>
<p><button>Submit order</button><p>
</form>
It is also possible to limit the length of the input, using the
maxlength attribute. By
adding this to the textarea element, we can limit users
to 1000 characters, preventing them from writing huge essays to the
busy delivery drivers instead of staying focused and to the
point:
<form method="post"
enctype="application/x-www-form-urlencoded"
action="https://pizza.example.com/order.cgi">
<p><label>Customer name: <input name="custname" required></label></p>
<p><label>Telephone: <input type=tel name="custtel"></label></p>
<p><label>E-mail address: <input type=email name="custemail"></label></p>
<fieldset>
<legend> Pizza Size </legend>
<p><label> <input type=radio name=size value="small"> Small </label></p>
<p><label> <input type=radio name=size value="medium"> Medium </label></p>
<p><label> <input type=radio name=size value="large"> Large </label></p>
</fieldset>
<fieldset>
<legend> Pizza Toppings </legend>
<p><label> <input type=checkbox name="topping" value="bacon"> Bacon </label></p>
<p><label> <input type=checkbox name="topping" value="cheese"> Extra Cheese </label></p>
<p><label> <input type=checkbox name="topping" value="onion"> Onion </label></p>
<p><label> <input type=checkbox name="topping" value="mushroom"> Mushroom </label></p>
</fieldset>
<p><label>Preferred delivery time: <input type=time min="11:00" max="21:00" step="900" name="delivery" required></label></p>
<p><label>Delivery instructions: <textarea name="comments" maxlength=1000></textarea></label></p>
<p><button>Submit order</button><p>
</form>
Mostly for historical reasons, elements in this section fall into several overlapping (but subtly different) categories in addition to the usual ones like flow content, phrasing content, and interactive content.
A number of the elements are form-associated elements, which means they can have a
form owner and, to expose this, have a form content attribute with a matching
form IDL attribute.
The form-associated elements fall into several subcategories:
Denotes elements that are listed in the form.elements
and fieldset.elements APIs.
Denotes elements that can be associated with label
elements.
Denotes elements that can be used for constructing the form data
set when a form element is submitted.
Denotes elements that can be affected when a form
element is reset.
In addition, some submittable elements can be, depending on their attributes, buttons. The prose below defines when an element is a button. Some buttons are specifically submit buttons.
The object element is also a
form-associated element and can, with the use of a
suitable plugin, partake in form
submission.
form elementform element descendants.accept-charsetactionautocompleteenctypemethodnamenovalidatetarget[OverrideBuiltins]
interface HTMLFormElement : HTMLElement {
attribute DOMString acceptCharset;
attribute DOMString action;
attribute boolean autocomplete;
attribute DOMString enctype;
attribute DOMString method;
attribute DOMString name;
attribute boolean noValidate;
attribute DOMString target;
readonly attribute HTMLFormControlsCollection elements;
readonly attribute long length;
caller getter any item(in unsigned long index);
caller getter any namedItem(in DOMString name);
void submit();
void reset();
boolean checkValidity();
void dispatchFormInput();
void dispatchFormChange();
};
The form element represents a
collection of form-associated
elements, some of which can represent editable values that
can be submitted to a server for processing.
The accept-charset
attribute gives the character encodings that are to be used for the
submission. If specified, the value must be an ordered set of
unique space-separated tokens, and each token must be an
ASCII case-insensitive match for the preferred
MIME name of an ASCII-compatible character
encoding. [IANACHARSET]
The name attribute
represents the form's name within the forms collection. The value must
not be the empty string, and the value must be unique amongst the
form elements in the forms collection that it is in, if
any.
The autocomplete
attribute is an enumerated attribute. The attribute has
two states. The on
keyword maps to the on state, and the
off keyword maps to
the off
state. The attribute may also be omitted. The missing value
default is the on state. The off state indicates
that by default, input elements in the form will have
their resulting autocompletion state set to off; the on state indicates
that by default, input elements in the form will have
their resulting autocompletion state set to on.
The action, enctype, method, novalidate, and target attributes are attributes
for form submission.
elementsReturns an HTMLCollection of the form controls in
the form (excluding image buttons for historical reasons).
lengthReturns the number of form controls in the form (excluding image buttons for historical reasons).
item(index)Returns the indexth element in the form (excluding image buttons for historical reasons).
namedItem(name)Returns the form control in the form with the given ID or name (excluding image buttons for
historical reasons).
Once an element has been referenced using a particular name,
that name will continue being available as a way to reference that
element in this method, even if the element's actual ID or name changes, for as long as the
element remains in the Document.
If there are multiple matching items, then a
NodeList object containing all those elements is
returned.
Returns null if no element with that ID or name could be found.
submit()Submits the form.
reset()Resets the form.
checkValidity()Returns true if the form's controls are all valid; otherwise, returns false.
dispatchFormInput()Dispatches a forminput event at all the form controls.
dispatchFormChange()Dispatches a formchange event at all the form controls.
The autocomplete and
name IDL attributes
must reflect the respective content attributes of the
same name.
The acceptCharset IDL
attribute must reflect the accept-charset content
attribute.
The elements
IDL attribute must return an HTMLFormControlsCollection
rooted at the Document node, whose filter matches listed elements whose form
owner is the form element, with the exception of
input elements whose type attribute is in the Image Button state, which must,
for historical reasons, be excluded from this particular
collection.
The length IDL
attribute must return the number of nodes represented by the elements collection.
The
indices of the supported indexed properties at any
instant are the indices supported by the object returned by the
elements attribute at that
instant.
The item(index) method must return the value
returned by the method of the same name on the elements collection, when invoked
with the same argument.
Each form element has a mapping of names to elements
called the past names map. It is used to persist names of
controls even when they change names.
The names of the supported named properties are the
union of the names currently supported by the object returned by the
elements attribute, and the
names currently in the past names map.
The namedItem(name) method, when called, must run the
following steps:
If name is one of the names of the
supported named properties of the object returned by the
elements attribute, then
run these substeps:
Let candidate be the object returned
by the namedItem()
method on the object returned by the elements attribute when passed
the name argument.
If candidate is an element, then add a
mapping from name to candidate in the form element's
past names map, replacing the previous entry with
the same name, if any.
Return candidate and abort these steps.
Otherwise, name is the name of one of
the entries in the form element's past names
map: return the object associated with name in that map.
If an element listed in the form element's past
names map is removed from the Document, then its
entries must be removed from the map.
The submit()
method, when invoked, must submit the form
element from the form element itself, with the scripted-submit flag set.
The reset()
method, when invoked, must run the following steps:
If the form element is marked as locked for
reset, then abort these steps.
Mark the form element as locked for
reset.
Unmark the form element as locked for
reset.
If the checkValidity()
method is invoked, the user agent must statically validate the
constraints of the form element, and return true
if the constraint validation return a positive result, and
false if it returned a negative result.
If the dispatchFormInput()
method is invoked, the user agent must broadcast forminput events from the
form element.
If the dispatchFormChange()
method is invoked, the user agent must broadcast formchange events from the
form element.
This example shows two search forms:
<form action="http://www.google.com/search" method="get"> <label>Google: <input type="search" name="q"></label> <input type="submit" value="Search..."> </form> <form action="http://www.bing.com/search" method="get"> <label>Bing: <input type="search" name="q"></label> <input type="submit" value="Search..."> </form>
fieldset elementlegend element, followed by flow content.disabledformnameinterface HTMLFieldSetElement : HTMLElement {
attribute boolean disabled;
readonly attribute HTMLFormElement form;
attribute DOMString name;
readonly attribute DOMString type;
readonly attribute HTMLFormControlsCollection elements;
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(in DOMString error);
};
The fieldset element represents a set
of form controls optionally grouped under a common name.
The name of the group is given by the first legend
element that is a child of the fieldset element, if
any. The remainder of the descendants form the group.
The disabled
attribute, when specified, causes all the form control descendants
of the fieldset element, excluding those that are
descendants of the fieldset element's first
legend element child, if any, to be disabled.
The form attribute is used to
explicitly associate the fieldset element with its
form owner. The name
attribute represents the element's name.
typeReturns the string "fieldset".
elementsReturns an HTMLCollection of the form controls in
the element.
The disabled IDL
attribute must reflect the content attribute of the
same name.
The type IDL
attribute must return the string "fieldset".
The elements IDL
attribute must return an HTMLFormControlsCollection
rooted at the fieldset element, whose filter matches
listed elements.
The willValidate,
validity, and validationMessage
attributes, and the checkValidity() and
setCustomValidity()
methods, are part of the constraint validation API.
Constraint validation: fieldset
elements are always barred from constraint
validation.
The following snippet shows a fieldset with a checkbox in the legend that controls whether or not the fieldset is enabled. The contents of the fieldset consist of two required text fields and an optional year/month control.
<fieldset name="clubfields" disabled> <legend> <label> <input type=checkbox name=club onchange="form.clubfields.disabled = !checked"> Use Club Card </label> </legend> <p><label>Name on card: <input name=clubname required></label></p> <p><label>Card number: <input name=clubnum required pattern="[-0-9]+"></label></p> <p><label>Expiry date: <input name=clubexp type=month></label></p> </fieldset>
legend elementfieldset element.interface HTMLLegendElement : HTMLElement {
readonly attribute HTMLFormElement form;
};
The legend element represents a caption
for the rest of the contents of the legend element's
parent fieldset element, if
any.
formReturns the element's form element, if any, or
null otherwise.
The form IDL
attribute's behavior depends on whether the legend
element is in a fieldset element or not. If the
legend has a fieldset element as its
parent, then the form IDL
attribute must return the same value as the form IDL attribute on that
fieldset element. Otherwise, it must return null.
label elementlabel elements.formforinterface HTMLLabelElement : HTMLElement {
readonly attribute HTMLFormElement form;
attribute DOMString htmlFor;
readonly attribute HTMLElement control;
};
The label represents a caption in a
user interface. The caption can be associated with a specific form
control, known as the label
element's labeled control, either using for attribute, or by putting the form
control inside the label element itself.
Except where otherwise specified by the following rules, a
label element has no labeled control.
The for attribute
may be specified to indicate a form control with which the caption
is to be associated. If the attribute is specified, the attribute's
value must be the ID of a labelable
form-associated element in the same Document as
the label element. If the attribute
is specified and there is an element in the Document
whose ID is equal to the value of the for attribute, and the first such
element is a labelable form-associated
element, then that element is the label
element's labeled control.
If the for attribute is not
specified, but the label element has a labelable form-associated element
descendant, then the first such descendant in tree
order is the label element's labeled
control.
The label element's exact default presentation and
behavior, in particular what its activation behavior
might be, if anything, should match the platform's label
behavior.
For example, on platforms where clicking a checkbox label checks
the checkbox, clicking the label in the following
snippet could trigger the user agent to run synthetic click
activation steps on the input element, as if
the element itself had been triggered by the user:
<label><input type=checkbox name=lost> Lost</label>
On other platforms, the behavior might be just to focus the control, or do nothing.
controlReturns the form control that is associated with this element.
The form attribute is used to
explicitly associate the label element with its
form owner.
The htmlFor IDL
attribute must reflect the for content attribute.
The control IDL
attribute must return the label element's labeled
control, if any, or null if there isn't one.
labelsReturns a NodeList of all the label
elements that the form control is associated with.
Labelable form-associated
elements have a NodeList object associated with
them that represents the list of label elements, in
tree order, whose labeled control is the
element in question. The labels IDL attribute of
labelable form-associated
elements, on getting, must return that NodeList
object.
The following example shows three form controls each with a label, two of which have small text showing the right format for users to use.
<p><label>Full name: <input name=fn> <small>Format: First Last</small></label></p> <p><label>Age: <input name=age type=number min=0></label></p> <p><label>Post code: <input name=pc> <small>Format: AB12 3CD</small></label></p>
input elementtype attribute is not in the Hidden state: Interactive content.acceptaltautocompleteautofocuscheckeddisabledformformactionformenctypeformmethodformnovalidateformtargetheightlistmaxmaxlengthminmultiplenamepatternplaceholderreadonlyrequiredsizesrcsteptypevaluewidthinterface HTMLInputElement : HTMLElement {
attribute DOMString accept;
attribute DOMString alt;
attribute boolean autocomplete;
attribute boolean autofocus;
attribute boolean defaultChecked;
attribute boolean checked;
attribute boolean disabled;
readonly attribute HTMLFormElement form;
readonly attribute FileList files;
attribute DOMString formAction;
attribute DOMString formEnctype;
attribute DOMString formMethod;
attribute boolean formNoValidate;
attribute DOMString formTarget;
attribute DOMString height;
attribute boolean indeterminate;
readonly attribute HTMLElement list;
attribute DOMString max;
attribute long maxLength;
attribute DOMString min;
attribute boolean multiple;
attribute DOMString name;
attribute DOMString pattern;
attribute DOMString placeholder;
attribute boolean readOnly;
attribute boolean required;
attribute unsigned long size;
attribute DOMString src;
attribute DOMString step;
attribute DOMString type;
attribute DOMString defaultValue;
attribute DOMString value;
attribute Date valueAsDate;
attribute float valueAsNumber;
readonly attribute HTMLOptionElement selectedOption;
attribute DOMString width;
void stepUp(in optional long n);
void stepDown(in optional long n);
readonly attribute boolean willValidate;
readonly attribute ValidityState validity;
readonly attribute DOMString validationMessage;
boolean checkValidity();
void setCustomValidity(in DOMString error);
readonly attribute NodeList labels;
void select();
attribute unsigned long selectionStart;
attribute unsigned long selectionEnd;
void setSelectionRange(in unsigned long start, in unsigned long end);
};