Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): add scope="col" to Table column headers (#3715)

Baraa Hamodi2935f1841591
diff --git a/.changeset/table-th-scope.md b/.changeset/table-th-scope.md
new file mode 100644
index 0000000000..7f4395ddb3
--- /dev/null
+++ b/.changeset/table-th-scope.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Table: column headers now render with `scope="col"` so screen readers correctly associate data cells with their column headers. Consumer-provided scope via column header props still takes precedence. (#3715)
+@bhamodi
diff --git a/packages/core/src/Table/BaseTable.tsx b/packages/core/src/Table/BaseTable.tsx
index 375c2faf34..b2a15e8f18 100644
--- a/packages/core/src/Table/BaseTable.tsx
+++ b/packages/core/src/Table/BaseTable.tsx
@@ -371,9 +371,13 @@ function BaseTableInner<T extends Record<string, unknown>>({
const headerCells = resolvedColumns.map((col, columnIndex) => {
const headerContent = col.header ?? col.key;
- // Build initial htmlProps with column alignment if specified
+ // Build initial htmlProps with column alignment if specified.
+ // `scope: 'col'` is the default so every column header associates its
+ // data cells with the correct column for screen readers; a plugin's
+ // transformHeaderCell can override it via htmlProps.scope.
const initialHeaderHtmlProps: Record<string, unknown> = {
'data-column-key': col.key,
+ scope: 'col',
};
if (col.align) {
initialHeaderHtmlProps.style = {textAlign: col.align};
diff --git a/packages/core/src/Table/Table.test.tsx b/packages/core/src/Table/Table.test.tsx
index 6659be05d5..a0576db578 100644
--- a/packages/core/src/Table/Table.test.tsx
+++ b/packages/core/src/Table/Table.test.tsx
@@ -229,6 +229,34 @@ describe('BaseTable', () => {
expect(headers[2]).toHaveTextContent('Email');
});
+ it('renders every column header with scope="col"', () => {
+ render(<BaseTable data={users} columns={columns} />);
+ const headers = screen.getAllByRole('columnheader');
+ expect(headers).toHaveLength(3);
+ for (const header of headers) {
+ expect(header).toHaveAttribute('scope', 'col');
+ }
+ });
+
+ it('lets a consumer override scope via header html props', () => {
+ // A `<th scope="row">` maps to the `rowheader` role, so query the DOM
+ // directly to assert the attribute regardless of the resolved ARIA role.
+ const plugin: TablePlugin<User> = {
+ transformHeaderCell: (props, column) =>
+ column.key === 'name'
+ ? {...props, htmlProps: {...props.htmlProps, scope: 'row'}}
+ : props,
+ };
+ const {container} = render(
+ <BaseTable data={users} columns={columns} plugins={[plugin]} />,
+ );
+ const headerCells = container.querySelectorAll('thead th');
+ // columns fixture order: name, age, email — plugin overrides name → 'row'
+ expect(headerCells[0]).toHaveAttribute('scope', 'row');
+ expect(headerCells[1]).toHaveAttribute('scope', 'col');
+ expect(headerCells[2]).toHaveAttribute('scope', 'col');
+ });
+
it('renders data cells', () => {
render(<BaseTable data={users} columns={columns} />);
const cells = screen.getAllByRole('cell');