References

Beginner-friendly references for web development, with live, editable examples.

The HTML colspan attribute

Attribute All modern browsers Updated
In short

The HTML colspan attribute makes a table cell stretch across several columns. It works on <td> and <th>, like merging cells in a spreadsheet. Its value is a whole number from 1 to 1000, the default is 1, and browsers treat anything above 1000 as 1000.

Overview

The colspan attribute sets how many columns a table cell covers. It works on <td> and <th>, and a cell with colspan="3" takes the space of three ordinary cells in its row.

The value must be an integer greater than zero and no more than 1000. Browsers parse it forgivingly, so zero, a negative number or text becomes 1, and anything over 1000 is clamped to 1000. The colSpan property in JavaScript reflects the attribute with the same 1 to 1000 range.

Spanning cells change how you count. Each row's cells, with their spans added up, should cover the same number of columns, and the HTML Standard forbids spans that make two cells overlap. When one row adds up to more columns than the rest, the table widens and the shorter rows leave the extra slots empty.

For a header that covers several columns, W3C's accessibility tutorial pairs colspan with scope set to colgroup and groups the columns with <colgroup>. Outside tables, colspan does nothing, and a CSS grid item gets the same effect with grid-column: span 2.

Syntax

<td colspan="2">Spans two columns</td>

Values

Value
A whole number from 1 to 1000 (default 1).

Example

Live example 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Units sold by region</title>
  <style>
    table { border-collapse: collapse; font: 14px sans-serif; }
    th, td { border: 1px solid #cbd5e1; padding: 6px 10px; text-align: left; }
  </style>
</head>
<body>
  <table>
    <caption>Units sold by region</caption>
    <colgroup><col></colgroup>
    <colgroup span="2"></colgroup>
    <tr><td></td><th colspan="2" scope="colgroup">Q3</th></tr>
    <tr><th scope="col">Region</th><th scope="col">July</th><th scope="col">August</th></tr>
    <tr><th scope="row">North</th><td>120</td><td>135</td></tr>
    <tr><th scope="row">South</th><td>98</td><td>104</td></tr>
    <tr><th scope="row">Q3 total</th><td colspan="2">457</td></tr>
  </table>
</body>
</html>

Best practices

  • Check that every row adds up to the same number of columns once spans are counted, or rows will end with empty gaps.
  • Give a spanning header cell scope="colgroup" and wrap the columns it covers in a matching <colgroup>, so screen readers know which columns it heads.
  • Use colspan for data that genuinely covers several columns, like a total or a group heading. The HTML Standard says tables must not be used as layout aids.
  • Consider splitting a table with multi-level headers into smaller tables, which W3C's tutorial on multi-level headers suggests to make the information less complex for all readers.

Accessibility

A header cell that spans columns needs its reach spelled out. W3C's table tutorial sets scope="colgroup" on such a <th> and defines the column groups with <colgroup>, so assistive technology can tie each data cell to the right heading.

Scope alone is not enough for tables with multi-level headers. For those, the tutorial gives each header an id and lists the relevant ids in the headers attribute of every data cell.

Frequently asked questions

What does colspan do in HTML?
The colspan attribute makes a table cell span more than one column. A cell with colspan set to 2 fills the width of two normal cells in its row.
What is the maximum value of colspan?
The maximum valid colspan is 1000. Larger values are clamped to 1000, and zero or invalid values fall back to 1.
Can I use colspan and rowspan on the same cell?
Yes, one cell can carry both colspan and rowspan to cover a block of rows and columns. The block must not overlap another cell, which the HTML Standard forbids.
When should I avoid colspan?
Avoid colspan when a table is only there for page layout, which the HTML Standard does not allow. Also avoid spans that leave it unclear which header a value belongs to.
Does colspan work on div elements or in CSS?
No, colspan only works on td and th cells inside a table. In a CSS grid, grid-column: span 2 gives an item the same kind of span.
How do I set colspan with JavaScript?
Set the cell's colSpan property, for example cell.colSpan = 3. The property reflects the colspan attribute and keeps values between 1 and 1000.
cols command