The HTML table model allows users to organize data in complex tabular structures. Tables can include lists, paragraphs, forms, figures, preformatted text, and other tables.
In this table model, rows and columns may be grouped together. This grouping conveys structural information about the table and may be rendered by user agents in ways to emphasize this structure.
Row groups are particularly useful in large tables. Intelligent visual user agents may allow scrolling of a table body while preserving the head and foot information on the screen. Similarly, when long tables are printed, the head and foot information may be repeated on each page that contains table data.
Note: This specification includes more detailed information about tables in sections on table design rationale and implementation issues.
An HTML table has the following structure:
<!ELEMENT TABLE - - (CAPTION?, (COL*|COLGROUP*), THEAD?, TFOOT?, TBODY+)> <!ATTLIST TABLE -- table element -- %attrs; -- %coreattrs, %i18n, %events -- align %TAlign; #IMPLIED -- table position relative to window -- bgcolor %Color #IMPLIED -- background color for cells -- width CDATA #IMPLIED -- table width relative to window -- cols NUMBER #IMPLIED -- used for immediate display mode -- border CDATA #IMPLIED -- controls frame width around table -- frame %TFrame; #IMPLIED -- which parts of table frame to include -- rules %TRules; #IMPLIED -- rulings between rows and cols -- cellspacing CDATA #IMPLIED -- spacing between cells -- cellpadding CDATA #IMPLIED -- spacing within cells -- >
Start tag: required, End tag: required
Attribute definitions
Attributes defined elsewhere
The TABLE element contains all other elements that specify caption, rows, content, and formatting.
The number of rows in a table is equal to the number of TR elements it contains. User agents should ignore rows that are implied by cells spanning rows beyond this number.
There are several ways to determine the number of columns:
User agents can assume that the table in this example has three columns.
<TABLE cols="3"> ...the rest of the table... </TABLE>
If the number of columns in a table is not specified by the cols attribute, a visual user agent may wait for the entire table to arrive before beginning rendering. In general waiting until the end of the table allows the number of columns and their widths to be determined without the need for a redisplay. Setting the cols attribute acts as a hint to visual user agents to display tables as each row is received. Authors are recommended to use the COL and COLGROUP elements to specify column properties rather than using the cols attribute.
The directionality of a table is specified by the dir attribute for the TABLE element. For a left-to-right table (the default), column one is on the left side of the table and row one is at the top. For a right-to-left table, column one is one the right side and row one is at the top.
Similarly, for left-to-right tables (the default), extra row cells are added to the right of the table, and for right-to-left tables, extra cells are added to the left side.
When set for the TABLE element, the dir attribute also affects the direction of text within table cells (since the dir attribute is inherited by block-level elements).
To specify a right-to-left table, set the dir attribute as follows:
<TABLE dir="RTL"> ...the rest of the table... </TABLE>
The direction of text in individual cells can be changed by setting the dir attribute in element that defines the cell. Please consult the section on bidirectional text for more information on text direction issues.
<!ELEMENT CAPTION - - (%inline;)+> <!ENTITY % CAlign "(top|bottom|left|right)"> <!ATTLIST CAPTION -- table caption -- %attrs; -- %coreattrs, %i18n, %events -- align %CAlign; #IMPLIED -- relative to table -- >
Start tag: required, End tag: required
Attribute definitions
Attributes defined elsewhere
When present, the CAPTION element's text should describe the nature of the table. The CAPTION element must come immediately after the TABLE start tag.
For instance,
<TABLE cols="3"> <CAPTION>Cups of coffee consumed by each senator</CAPTION> ...the rest of the table... </TABLE>
<!ELEMENT THEAD - O (TR+)> <!ELEMENT TFOOT - O (TR+)>
Start tag: required, End tag: optional
<!ELEMENT TBODY O O (TR+)>
Start tag: optional, End tag: optional
<!ATTLIST (THEAD|TBODY|TFOOT) -- table section -- %attrs; -- %coreattrs, %i18n, %events -- %cellhalign; -- horizontal alignment in cells -- %cellvalign; -- vertical alignment in cells -- >
Attributes defined elsewhere
A table must contain at least one row group. Each row group is divided into three sections: head, body, and foot. The head and foot sections are optional. The THEAD element defines the head, the TFOOT element defines the foot, and the TBODY element defines the body.
When present, each THEAD, TFOOT, and TBODY instance must contain one or more rows (see TR).
This example illustrates the order and structure of table heads, feet, and bodies.
<TABLE>
<THEAD>
<TR> ...header information...
</THEAD>
<TFOOT>
<TR> ...footer information...
</TFOOT>
<TBODY>
<TR> ...first row of block one data...
<TR> ...second row of block one data...
</TBODY>
<TBODY>
<TR> ...first row of block two data...
<TR> ...second row of block two data...
<TR> ...third row of block two data...
</TBODY>
</TABLE>
TFOOT must appear before TBODY within a TABLE definition so that user agents can render the foot before receiving all of the (potentially numerous) rows of data.
Conforming user agent parsers must obey these rules for reasons of backward compatibility.
The table of the previous example could be shortened by removing certain end tags.
<TABLE>
<THEAD>
<TR> ...header information...
<TFOOT>
<TR> ...footer information...
<TBODY>
<TR> ...first row of block one data...
<TR> ...second row of block one data...
<TBODY>
<TR> ...first row of block two data...
<TR> ...second row of block two data...
<TR> ...third row of block two data...
</TABLE>
<!ELEMENT COLGROUP - O (col*)> <!ATTLIST COLGROUP %attrs; -- %coreattrs, %i18n, %events -- span NUMBER 1 -- default number of columns in group -- width CDATA #IMPLIED -- default width for enclosed COLs -- %cellhalign; -- horizontal alignment in cells -- %cellvalign; -- vertical alignment in cells -- >
Start tag: required, End tag: optional
Attribute definitions
Attributes defined elsewhere
A table must contain at least one column group. In the absence of any column group definitions, a table is considered to have one column group that includes all columns in the table. The COLGROUP element creates an explicit column group.
The width attribute of the COLGROUP element specifies a default width for each column in a column group. The special value "0*" tells user agents to set every column in a group to its minimum width. This behavior may be overridden by the presence of a COL element.
The table in the following example contains two column groups. The first column group contains 10 columns and the second contains 5 columns. The default width for each column in the first column group is 50 pixels. The width of each column in the second column group will be the minimum for the column.
<TABLE> <COLGROUP span="10" width="50"> <COLGROUP span="5" width="0*"> <THEAD> <TR> ... </TABLE>
<!ELEMENT COL - O EMPTY> <!ATTLIST COL -- column groups and properties -- %attrs; -- %coreattrs, %i18n, %events -- span NUMBER 1 -- number of columns spanned by group -- width CDATA #IMPLIED -- column width specification -- %cellhalign; -- horizontal alignment in cells -- %cellvalign; -- vertical alignment in cells -- >
Start tag: required, End tag: forbidden
Attribute definitions
Attributes defined elsewhere
Each column group defined by COLGROUP may contain zero or more COL elements. A COL element does not define a column group in the same sense as COLGROUP; it is simply a way to share attribute values among columns in a column group. Note that COL elements are empty; they are only affected by attributes.
The span attribute for COL means the following:
As for COLGROUP, the width attribute for COL affects the width of the columns subsumed by the element. If a COL element spans several columns then its width attribute specifies the width of each column in the span, not the width of the span as a whole.
The table in this example contains two column groups. The first group contains three columns, the second contains two columns. The available horizontal space will be alloted as follows: First the user agent will allot 30 pixels to the first column. Then, the minimal space required for the second column will be alloted to it. The remaining horizontal space will be divided into six equal portions. Column three will receive two of these portions, column four will receive one, and column five will receive three.
<TABLE> <COLGROUP> <COL width="30"> <COL width="0*"> <COL width="2*"> <COLGROUP align="center"> <COL width="1*"> <COL width="3*" align="char" char=":"> <THEAD> <TR> ... </TABLE>
We have set the value of the align attribute in the second column group to "center". All cells in every column in this group will inherit this value, but may override it. In fact, the final COL does just that, by specifying that every cell in the column it governs will be aligned along the ":" character.
<!ELEMENT TR - O (TH|TD)+> <!ATTLIST TR -- table row -- %attrs; -- %coreattrs, %i18n, %events -- %cellhalign; -- horizontal alignment in cells -- %cellvalign; -- vertical alignment in cells -- bgcolor %Color #IMPLIED -- background color for row -- >
Start tag: required, End tag: optional
Attributes defined elsewhere
The TR elements acts as a container for a row of table cells.
This sample table contains three rows, each begun by the TR element:
<TABLE> <CAPTION>Cups of coffee consumed by each senator</CAPTION> <TR> ...A header row... <TR> ...First row of data... <TR> ...Second row of data... ...the rest of the table... </TABLE>
<!ELEMENT (TH|TD) - O %block> <!ATTLIST (TH|TD) -- header or data cell -- %attrs; -- %coreattrs, %i18n, %events -- axis CDATA #IMPLIED -- defaults to cell content -- axes CDATA #IMPLIED -- list of axis names -- nowrap (nowrap) #IMPLIED -- suppress word wrap -- bgcolor %Color #IMPLIED -- cell background color -- rowspan NUMBER 1 -- number of rows spanned by cell -- colspan NUMBER 1 -- number of cols spanned by cell -- %cellhalign; -- horizontal alignment in cells -- %cellvalign; -- vertical alignment in cells -- >
Start tag: required, End tag: optional
Attribute definitions
Attributes defined elsewhere
The TH element stores header information, while the TD element stores data. This distinction enables user agents to render header and data cells distinctly, even in the absence of style sheets.
Cells may be empty (i.e., contain no data).
The following table contains four columns of data, each headed by a column description.
<TABLE> <CAPTION>Cups of coffee consumed by each senator</CAPTION> <TR> <TH>Name <TH>Cups <TH>Type of Coffee <TH>Sugar? <TR> <TD>T. Sexton <TD>10 <TD>Espresso <TD>No <TR> <TD>J. Dinnen <TD>5 <TD>Decaf <TD>Yes ...the rest of the table... </TABLE>
Your user agent renders the beginning of this table as follows:
| Name | Cups | Type of Coffee | Sugar? |
|---|---|---|---|
| T. Sexton | 10 | Espresso | No |
| J. Dinnen | 5 | Decaf | Yes |
To help distinguish the cells of this table, we can set the border attribute of the TABLE element:
<TABLE border="border"> ...the rest of the table... </TABLE>
With a border, your user agent renders the beginning of this table as follows:
| Name | Cups | Type of Coffee | Sugar? |
|---|---|---|---|
| T. Sexton | 10 | Espresso | No |
| J. Dinnen | 5 | Decaf | Yes |
The axis and axes attributes provide a means for specifying cell labels.
Speech synthesizers may use these labels to identify the contents and location of each cell. Processing software might consider these labels as database field names when transferring a table's contents to a database.
In the following example table, we set the value of the axis attribute to be the last name of each senator. We also label the cell value as falling under the "Name" column.
<TABLE border="border"> <CAPTION>Cups of coffee consumed by each senator</CAPTION> <TR> <TH>Name <TH>Cups <TH>Type of Coffee <TH>Sugar? <TR> <TD axis="Sexton" axes="Name">T. Sexton <TD>10 <TD>Espresso <TD>No <TR> <TD axis="Dinnen" axes="Name">J. Dinnen <TD>5 <TD>Decaf <TD>Yes </TABLE>
Cells may span several rows or columns. The number of rows or columns spanned by a cell is set by the rowspan and colspan attributes for either the TH or TD elements.
In this table definition, we specify that the cell in row four, column two should span a total of three columns, including the current row.
<TABLE border="border"> <CAPTION>Cups of coffee consumed by each senator</CAPTION> <TR> <TH>Name <TH>Cups <TH>Type of Coffee <TH>Sugar? <TR> <TD>T. Sexton <TD>10 <TD>Espresso <TD>No <TR> <TD>J. Dinnen <TD>5 <TD>Decaf <TD>Yes <TR> <TD>A. Soria <TD colspan="3"><em>Not available</em> </TABLE>
This table might be rendered by a visual user agent as follows:
Cups of coffee consumed by each senator -------------------------------------- | Name |Cups|Type of Coffee|Sugar?| -------------------------------------- |T. Sexton|10 |Espresso |No | -------------------------------------- |J. Dinnen|5 |Decaf |Yes | -------------------------------------- |A. Soria |Not available | --------------------------------------
This example illustrates how cell definitions that span more than one row or column affect the definition of later cells. Consider the following table definition:
<TABLE border="border"> <TR><TD>1 <TD rowspan="2">2 <TD>3 <TR><TD>4 <TD>6 <TR><TD>7 <TD>8 <TD>9 </TABLE>
This table might be rendered something like this:
------------- | 1 | 2 | 3 | ----| |---- | 4 | | 6 | ----|---|---- | 7 | 8 | 9 | -------------
Since the cell labeled "2" spans two rows, it affects the positions of the cells defined in the following rows. Note that if cell "6" had not been defined in row two, an extra empty cell would have been added by the user agent to complete the row.
Similarly, in the following table definition:
<TABLE border="border"> <TR><TD>1 <TD>2 <TD>3 <TR><TD colspan="2">4 <TD>6 <TR><TD>7 <TD>8 <TD>9 </TABLE>
cell "4" spans two columns, so cell "6" is placed in column three.
------------- | 1 | 2 | 3 | --------|---- | 4 | 6 | --------|---- | 7 | 8 | 9 | -------------
This example illustrates how one might create overlapping cells. In this table, cell "5" spans two rows and cell "7" spans two columns, so there is overlap in the cell between "7" and "9":
<TABLE border="border"> <TR><TD>1 <TD>2 <TD>3 <TR><TD>4 <TD rowspan="2">5 <TD>6 <TR><TD colspan="2">7 <TD>9 </TABLE>
This table might be rendered as follows to convey the overlap:
------------- | 1 | 2 | 3 | ------------- | 4 | 5 | 6 | ----|...|---- | 7 : | 9 | -------------
The rendering of overlapping cells is undefined. Rendering will vary between user agents.
The following description describes the HTML table attributes that tell visual user agents how to format tables. Style sheets will offer better control of visual table formatting. At the writing of this specification, [CSS1] did not offer mechanisms to control all aspects of visual table formatting.
This version of HTML includes mechanisms to control:
The following attributes may be set for different table elements (see their definitions).
<!-- horizontal alignment attributes for cell contents --> <!ENTITY % cellhalign "align (left|center|right|justify|char) #IMPLIED char CDATA #IMPLIED -- alignment char, e.g. char=':' -- charoff CDATA #IMPLIED -- offset for alignment char --" > <!-- vertical alignment attributes for cell contents --> <!ENTITY % cellvalign "valign (top|middle|bottom|baseline) #IMPLIED" >
Attribute definitions
When charoff is used so set the offset of an alignment character, the direction of offset is determined by the current text direction (set by the dir attribute). In left-to-right texts (the default), offset is from the left margin. In right-to-left texts, offset is from the right margin.
The table in this example aligns a row of currency values along a decimal point. We set the alignment character to "." explicitly.
<TABLE border="border"> <COLGROUP> <COL><COL align="char" char="."> <THEAD> <TR><TH>Vegetable <TH>Cost per kilo <TBODY> <TR><TD>Lettuce <TD>$1 <TR><TD>Silver carrots <TD>$10.50 <TR><TD>Golden turnips <TD>$100.30 </TABLE>
The formatted table should look something like this:
------------------------------ | Vegetable |Cost per kilo| |--------------|-------------| |Lettuce | $1 | |--------------|-------------| |Silver carrots| $10.50| |--------------|-------------| |Golden turnips| $100.30| ------------------------------
The alignment of cell contents can be specified on a cell by cell basis, or inherited from enclosing elements, such as the row, column or the table itself.
The order of precedence (from highest to lowest) for the attributes align, char, and charoff is the following:
The order of precedence (from highest to lowest) for the attribute valign (as well as the other inherited attributes lang, dir, and style) is the following:
Furthermore, when rendering cells, horizontal alignment is determined by columns in preference to rows, while for vertical alignment, rows are given preference over columns.
The default alignment for cells depends on the user agent. However, user agents should substitute the default attribute for the current directionality (i.e., not just "left" in all cases).
User agents that do not support the "justify" value of the align attribute may substitute the "left" value.
The following attributes affect a table's external frame and internal rules.
Attribute definitions
In the following table, borders five pixels thick will be rendered on the left- and right-hand sides of the table and rules should be displayed between all columns.
<TABLE border="5" frame="vsides" rules="cols"> <TR> <TD>1 <TD>2 <TD>3 <TR> <TD>4 <TD>5 <TD>6 <TR> <TD>7 <TD>8 <TD>9 </TABLE>
The following settings should be observed by user agents for backwards compatibility.
Thus, for example:
<FRAME border="2"> <=> <FRAME border="2" frame="border" rules="all">
and
<FRAME border> <=> <FRAME frame="border" rules="all">
Note: The border attribute also defines the border behavior for the OBJECT and IMG elements, but takes different values for those elements.
Two attributes control spacing between and within cells.
Attribute definitions
In the following table, the cellspacing attribute specifies that cells will be separated from each other and from the table frame by twenty pixels. The cellpadding attribute specifies that the top margin of the cell and the bottom margin of the cell will each be separated from the cell's contents by 10% of the available vertical space (the total being 20%). Similarly, the left margin of the cell and the right margin of the cell will each be separated from the cell's contents by 10% of the available horizontal space (the total being 20%).
<TABLE> <TR cellspacing="20"> <TD>Data1 <TD cellpadding="20%">Data2 <TD>Data3 </TABLE>
If a table or given column has a fixed width, cellspacing and cellpadding may demand more space than assigned. We recommend that user agents give these attributes precedence over the width attribute when a conflict occurs, but this is not a requirement.
The following table samples illustrate the interaction of all the table elements.
In "ascii art", the following table:
<TABLE border="border">
<CAPTION>A test table with merged cells</CAPTION>
<TR><TH rowspan=2><TH colspan="2">Average
<TH rowspan="2">other<BR>category<TH>Misc
<TR><TH>height<TH>weight
<TR><TH align="left">males<TD>1.9<TD>0.003
<TR><TH align="left" rowspan="2">females<TD>1.7<TD>0.002
</TABLE>
would be rendered something like this:
A test table with merged cells
/--------------------------------------------------\
| | Average | other | Misc |
| |-------------------| category |--------|
| | height | weight | | |
|-----------------------------------------|--------|
| males | 1.9 | 0.003 | | |
|-----------------------------------------|--------|
| females | 1.7 | 0.002 | | |
\--------------------------------------------------/
On your browser, the table looks like this:
| Average | other category | Misc | ||
|---|---|---|---|---|
| height | weight | |||
| males | 1.9 | 0.003 | ||
| females | 1.7 | 0.002 | ||
This sample illustrates grouped rows and columns. The example is adapted from "Developing International Software", by Nadine Kano.
In "ascii art", the following table:
<TABLE border="2" frame="hsides" rules="groups"> <CAPTION>CODE-PAGE SUPPORT IN MICROSOFT WINDOWS</CAPTION> <COLGROUP align="center"> <COLGROUP align="left"> <COLGROUP align="center" span="2"> <COLGROUP align="center" span="3"> <THEAD valign="top"> <TR> <TH>Code-Page<br>ID <TH>Name <TH>ACP <TH>OEMCP <TH>Windows<br>NT 3.1 <TH>Windows<br>NT 3.51 <TH>Windows<br>95 <TBODY> <TR><TD>1200<TD>Unicode (BMP of ISO/IEC-10646)<TD><TD><TD>X<TD>X<TD>* <TR><TD>1250<TD>Windows 3.1 Eastern European<TD>X<TD><TD>X<TD>X<TD>X <TR><TD>1251<TD>Windows 3.1 Cyrillic<TD>X<TD><TD>X<TD>X<TD>X <TR><TD>1252<TD>Windows 3.1 US (ANSI)<TD>X<TD><TD>X<TD>X<TD>X <TR><TD>1253<TD>Windows 3.1 Greek<TD>X<TD><TD>X<TD>X<TD>X <TR><TD>1254<TD>Windows 3.1 Turkish<TD>X<TD><TD>X<TD>X<TD>X <TR><TD>1255<TD>Hebrew<TD>X<TD><TD><TD><TD>X <TR><TD>1256<TD>Arabic<TD>X<TD><TD><TD><TD>X <TR><TD>1257<TD>Baltic<TD>X<TD><TD><TD><TD>X <TR><TD>1361<TD>Korean (Johab)<TD>X<TD><TD><TD>**<TD>X <TBODY> <TR><TD>437<TD>MS-DOS United States<TD><TD>X<TD>X<TD>X<TD>X <TR><TD>708<TD>Arabic (ASMO 708)<TD><TD>X<TD><TD><TD>X <TR><TD>709<TD>Arabic (ASMO 449+, BCON V4)<TD><TD>X<TD><TD><TD>X <TR><TD>710<TD>Arabic (Transparent Arabic)<TD><TD>X<TD><TD><TD>X <TR><TD>720<TD>Arabic (Transparent ASMO)<TD><TD>X<TD><TD><TD>X </TABLE>
would be rendered something like this:
CODE-PAGE SUPPORT IN MICROSOFT WINDOWS
===============================================================================
Code-Page | Name | ACP OEMCP | Windows Windows Windows
ID | | | NT 3.1 NT 3.51 95
-------------------------------------------------------------------------------
1200 | Unicode (BMP of ISO 10646) | | X X *
1250 | Windows 3.1 Eastern European | X | X X X
1251 | Windows 3.1 Cyrillic | X | X X X
1252 | Windows 3.1 US (ANSI) | X | X X X
1253 | Windows 3.1 Greek | X | X X X
1254 | Windows 3.1 Turkish | X | X X X
1255 | Hebrew | X | X
1256 | Arabic | X | X
1257 | Baltic | X | X
1361 | Korean (Johab) | X | ** X
-------------------------------------------------------------------------------
437 | MS-DOS United States | X | X X X
708 | Arabic (ASMO 708) | X | X
709 | Arabic (ASMO 449+, BCON V4) | X | X
710 | Arabic (Transparent Arabic) | X | X
720 | Arabic (Transparent ASMO) | X | X
===============================================================================
On your user agent, this tables is rendered as follows:
| Code-Page ID | Name | ACP | OEMCP | Windows NT 3.1 | Windows NT 3.51 | Windows 95 |
|---|---|---|---|---|---|---|
| 1200 | Unicode (BMP of ISO/IEC-10646) | X | X | * | ||
| 1250 | Windows 3.1 Eastern European | X | X | X | X | |
| 1251 | Windows 3.1 Cyrillic | X | X | X | X | |
| 1252 | Windows 3.1 US (ANSI) | X | X | X | X | |
| 1253 | Windows 3.1 Greek | X | X | X | X | |
| 1254 | Windows 3.1 Turkish | X | X | X | X | |
| 1255 | Hebrew | X | X | |||
| 1256 | Arabic | X | X | |||
| 1257 | Baltic | X | X | |||
| 1361 | Korean (Johab) | X | ** | X | ||
| 437 | MS-DOS United States | X | X | X | X | |
| 708 | Arabic (ASMO 708) | X | X | |||
| 709 | Arabic (ASMO 449+, BCON V4) | X | X | |||
| 710 | Arabic (Transparent Arabic) | X | X | |||
| 720 | Arabic (Transparent ASMO) | X | X |
This example illustrates how COLGROUP can be used to group columns and set the default column alignment. Similarly, TBODY is used to group rows. The frame and rules attributes tell the user agent which borders and rules to render.