aria-colcount
The aria-colcount
attribute defines the total number of columns in a table
, grid
, or treegrid
when not all columns are present in the DOM.
Description
Some tables are very large, and it's not possible to show all the columns to the user. Or, it is possible, but having such a wide table would be a bad user experience. Use the aria-colcount
attribute to let assistive technologies know how many columns the table would have if all columns were present. The value is an integer representing the number of columns that make up the full table. If you don't know the total number of columns a table will have, but know they will not all be in the DOM, use the value -1, so aria-colcount="-1"
. This value tells the user agent that the current number of columns present in the DOM may not be the actual number of columns in the table.
If all columns in a table are present in the DOM, the aria-colcount
attribute isn't needed, as browsers automatically calculate the total number of columns. However, if only a portion of the columns is present in the DOM at a given moment, that is when this attribute is helpful and needed.
When using aria-colcount
when you have a known number of columns, make sure to also use aria-colindex
to label each column, or, if the columns are contiguous-if it's a group of columns in the original order with no breaks-label each row.
The following example shows a grid with 6 columns, of which columns 1, 2, 5, and 6 are displayed to the user. The total number of columns that make up the table is set as aria-colcount="6"
on the table itself. As the columns aren't contiguous, every cell
- in this case columnheader
and gridcell
elements - have the aria-colindex
attribute set.
<div role="grid" aria-colcount="6">
<div role="rowgroup">
<div role="row">
<div role="columnheader" aria-colindex="1">First name</div>
<div role="columnheader" aria-colindex="2">Last name</div>
<div role="columnheader" aria-colindex="5">City</div>
<div role="columnheader" aria-colindex="6">Zip</div>
</div>
</div>
<div role="rowgroup">
<div role="row">
<div role="gridcell" aria-colindex="1">Debra</div>
<div role="gridcell" aria-colindex="2">Burks</div>
<div role="gridcell" aria-colindex="5">New York</div>
<div role="gridcell" aria-colindex="6">14127</div>
</div>
</div>
…
</div>
The first rule of ARIA use is "if you can use a native feature with the semantics and behavior you require already built in, instead of repurposing an element and adding an ARIA role, state or property to make it accessible, then do so." If we employ native HTML semantics with <table>
, <th>
, <td>
, etc., the aria-colcount
attribute is still necessary, but the mark up is not as verbose. When using semantic table header elements and not all columns are in the DOM, the aria-colcount
must still be used, but the aria-colindex
attribute only needs to be defined once per column in the column header <th>
.
<table aria-colcount="6">
<thead>
<tr>
<th aria-colindex="1" scope="col">First name</th>
<th aria-colindex="2" scope="col">Last name</th>
<th aria-colindex="5" scope="col">City</th>
<th aria-colindex="6" scope="col">Zip</th>
</tr>
</thead>
<tbody>
<tr>
<td>Debra</td>
<td>Burks</td>
<td>New York</td>
<td>14127</td>
</tr>
…
</tbody>
</table>
Values
<integer>
-
The number of columns in the full table
Associated roles
Specifications
Specification |
---|
Accessible Rich Internet Applications (WAI-ARIA) # aria-colcount |