ARIA ATTRIBUTE•Relationship Attributes
aria-colspan
Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.
Value Type
Integer (≥1)
Used With
cell, columnheader, rowheader
Default
1 (no spanning)
Overview
The aria-colspan attribute defines the number of columns spanned by a cell within a table, grid, or treegrid. It's the ARIA equivalent of the HTML colspan attribute.
Use this attribute when building custom grid components with role="grid" or role="treegrid" that have cells spanning multiple columns. For native HTML tables, the colspan attribute is preferred.
The value must be a positive integer. A value of 1 (the default) means the cell occupies a single column.
Live Demo: Schedule Grid with Spanning Cells
Time
Monday
Tuesday
Wednesday
Thursday
9:00 AM
Team Standup
aria-colspan="4"
10:00 AM
Dev Work
Code Review
aria-colspan="2"
Planning
11:00 AM
Sprint Planning
aria-colspan="3"
Free
Cells with aria-colspan span multiple columns. Screen readers announce the span, e.g., "Team Standup, column 2, spans 4 columns".
Code Examples
Basic Usage
<!-- aria-colspan indicates columns spanned by a cell -->
<table role="grid" aria-colcount="6">
<thead>
<tr>
<!-- Header spans 2 columns -->
<th aria-colindex="1" aria-colspan="2" scope="colgroup">
Personal Info
</th>
<!-- Header spans 3 columns -->
<th aria-colindex="3" aria-colspan="3" scope="colgroup">
Contact Details
</th>
<th aria-colindex="6">Status</th>
</tr>
<tr>
<th aria-colindex="1" scope="col">First Name</th>
<th aria-colindex="2" scope="col">Last Name</th>
<th aria-colindex="3" scope="col">Email</th>
<th aria-colindex="4" scope="col">Phone</th>
<th aria-colindex="5" scope="col">Address</th>
<th aria-colindex="6" scope="col">Active</th>
</tr>
</thead>
</table>Grid with Spanning Cells
<!-- aria-colspan in grid with spanning cells -->
<div role="grid" aria-colcount="4" aria-label="Weekly schedule">
<div role="row">
<div role="columnheader" aria-colindex="1">Time</div>
<div role="columnheader" aria-colindex="2">Monday</div>
<div role="columnheader" aria-colindex="3">Tuesday</div>
<div role="columnheader" aria-colindex="4">Wednesday</div>
</div>
<div role="row">
<div role="rowheader" aria-colindex="1">9:00 AM</div>
<!-- Meeting spans Mon-Wed (3 columns) -->
<div role="gridcell" aria-colindex="2" aria-colspan="3">
Team Meeting (All Week)
</div>
</div>
<div role="row">
<div role="rowheader" aria-colindex="1">10:00 AM</div>
<div role="gridcell" aria-colindex="2">Project Work</div>
<!-- Review spans Tue-Wed (2 columns) -->
<div role="gridcell" aria-colindex="3" aria-colspan="2">
Code Review
</div>
</div>
</div>Combined with Rowspan
<!-- Combining aria-colspan with aria-rowspan -->
<div role="grid" aria-colcount="4" aria-rowcount="4">
<div role="row" aria-rowindex="1">
<div role="columnheader" aria-colindex="1">Quarter</div>
<div role="columnheader" aria-colindex="2" aria-colspan="3">
Sales Metrics
</div>
</div>
<div role="row" aria-rowindex="2">
<!-- Row header spans 2 rows -->
<div role="rowheader" aria-colindex="1" aria-rowspan="2">
Q1 2024
</div>
<div role="gridcell" aria-colindex="2">$10,000</div>
<div role="gridcell" aria-colindex="3">$12,000</div>
<div role="gridcell" aria-colindex="4">$8,000</div>
</div>
<div role="row" aria-rowindex="3">
<!-- Cell spans columns 2-4 -->
<div role="gridcell" aria-colindex="2" aria-colspan="3">
Total: $30,000
</div>
</div>
</div>React Component
// React grid component with colspan support
import { useMemo } from 'react';
interface Cell {
content: string;
colIndex: number;
colspan?: number;
rowspan?: number;
isHeader?: boolean;
}
interface Row {
rowIndex: number;
cells: Cell[];
}
interface GridProps {
totalColumns: number;
totalRows: number;
rows: Row[];
label: string;
}
function AccessibleGrid({ totalColumns, totalRows, rows, label }: GridProps) {
return (
<div
role="grid"
aria-colcount={totalColumns}
aria-rowcount={totalRows}
aria-label={label}
>
{rows.map(row => (
<div key={row.rowIndex} role="row" aria-rowindex={row.rowIndex}>
{row.cells.map((cell, cellIndex) => {
const CellRole = cell.isHeader ? 'columnheader' : 'gridcell';
return (
<div
key={cellIndex}
role={CellRole}
aria-colindex={cell.colIndex}
aria-colspan={cell.colspan}
aria-rowspan={cell.rowspan}
tabIndex={cell.isHeader ? undefined : -1}
>
{cell.content}
</div>
);
})}
</div>
))}
</div>
);
}
// Usage example
function ScheduleGrid() {
const rows: Row[] = [
{
rowIndex: 1,
cells: [
{ content: 'Time', colIndex: 1, isHeader: true },
{ content: 'Mon', colIndex: 2, isHeader: true },
{ content: 'Tue', colIndex: 3, isHeader: true },
{ content: 'Wed', colIndex: 4, isHeader: true },
]
},
{
rowIndex: 2,
cells: [
{ content: '9:00', colIndex: 1, isHeader: true },
{ content: 'All-hands meeting', colIndex: 2, colspan: 3 },
]
},
];
return (
<AccessibleGrid
totalColumns={4}
totalRows={5}
rows={rows}
label="Weekly schedule"
/>
);
}