The <colgroup> Element

Technical summary

Definition, placement, and content model

Conforming HTML uses a positive integer from 1 to 1000 for span. When a colgroup has child col elements, those children define the columns, so the parent must not have span. The markup conformance rule is separate from how the DOM property handles an invalid value set by script.

span and column groups

There are two ways to describe a column group. Use colgroup span with no child col elements, or put col elements inside the group and set spans on those elements.

<!-- Method A: no child col; give the group a column count -->
<colgroup span="2"></colgroup>

<!-- Method B: give each child col a column count -->
<colgroup>
  <col span="2">
  <col>
</colgroup>

These are alternatives for different tables. In Method B, the first col represents two columns and the second represents one. The table model forms columns and column groups, then relates them to the slots occupied by row cells. A represented column does not, by itself, mean every slot in that column has a cell.

td colspan and col span do different jobs. The first says that one cell covers multiple columns. The second says how many columns the column element represents. Both affect table-grid formation and overlap checks.

Table model, parser, and DOM interface

colgroup is a direct child structure of table. In conforming content, it follows an optional caption and comes before thead and the table body. The HTML parser builds a DOM according to its table insertion modes. Parser recovery can insert elements into a tree; that does not make the input markup conforming.

Both colgroup and col use HTMLTableColElement. Its span IDL property is an unsigned long with a default of 1 and a reflected range of 1–1000. The interface does not define a dedicated collection API for all columns in a table.

const group = document.querySelector("colgroup");
const column = group.querySelector("col");

group instanceof HTMLTableColElement; // true
column instanceof HTMLTableColElement; // true
group.span;                            // 1 by default
column.span;                           // 1 by default

// The table's data cells are still descendants of rows,
// not descendants of colgroup or col.

CSS column boxes

HTML column elements do not contain table cells in the DOM. In the CSS table model, column and column-group boxes occupy separate layers, and only a limited set of properties applies to them. CSS 2.1 lists background, width, visibility, and border.

A CSS selector cannot select cells as descendants of colgroup. A column can receive some styles, such as a background, but column elements cannot control every property on text, padding, or cell borders. Browser implementation coverage here is limited to the stated fixture and WPT runs.

.highlighted-columns {
  background-color: #eaf3ff;
}

<colgroup span="2" class="highlighted-columns"></colgroup>

Header relationships and accessibility mappings

colgroup represents column structure; it does not provide heading text or create cell-to-header relationships. Use table cells with th and, as appropriate to the structure, scope or headers to describe headings. Use scope="colgroup" only when the header cell is anchored in a matching column group.

The HTML-AAM Editor's Draft does not map col to an ARIA role or to the listed platform APIs. colgroup has no computed role; the document lists ROLE_SYSTEM_GROUPING for MSAA + IAccessible2 and Group (localized control type colgroup) for UIA. It lists no mapping for ATK or Apple AX.

A specification mapping, a browser's exposed accessibility tree, an operating-system API, and screen-reader speech are separate evidence. The AAM observation below is a Chrome browser accessibility-tree query; it is not a direct measurement of a platform API or assistive technology.

Facts and evidence

Normative specification claims, CSS conditions, and AAM mappings are tied to their evidence. Observations and unmeasured scope are recorded separately below.

Evidence

1. HTML Standard: The colgroup element — meaning, context, content model, tag omission, span, and DOM interface
2. HTML Standard: The col element — context, empty content model, span, and table model
3. HTML Standard: The table element — permitted child order
4. HTML Standard: Forming a table — column groups, columns, slots, and cell spans
5. HTML Standard: The “in table” insertion mode — parser handling of table children
6. CSS 2.1: Columns — properties that apply to column and column-group boxes
7. HTML-AAM: colgroup and col — platform-specific role mappings
8. Web Platform Tests: col-span-limits.html — selected span reflection and table-layout checks
9. Web Platform Tests: colgroup-col.html — tentative CSS table column and group width checks

Implementation evidence

Browser implementation, selected WPTs, and accessibility-tree queries are recorded separately. Each result is limited to its stated environment, fixture, and test scope.

Coverage and open issues

• SPECMeaning, placement, content models, span, DOM interface, table model, CSS 2.1 column properties, and HTML-AAM mappings
• IMPLSelected observations in one Chrome fixture and environment. Other browsers, OS builds, print, and complex rowspan/colspan grids are unmeasured
• WPTSelected tests only. The wpt.live revision, full test directories, and other browsers were not checked
• AAMChrome browser accessibility-tree query only. Windows UI Automation, IAccessible2, ATK, Apple AX, and assistive-technology speech were not measured
• ReviewExpert-gap Review has not been completed

This Topic has initial coverage. Passing the selected fixture and WPTs does not establish identical behavior across all HTML structures, browsers, operating systems, CSS implementations, or assistive technologies.

Related surfaces

For beginner-friendly examples, see How to Use the colgroup Element and How to Use the col Element in Yugien. The column element is covered in the col Topic, the whole table structure in the table Topic, header rows in the thead Topic, header-cell relationships in the th Topic, and summary row groups in the tfoot Topic.