feat: structural accessibility for data table by oleksandrzavarzin-callstack · Pull Request #5082 · callstack/react-native-paper

oleksandrzavarzin-callstack · 2026-08-28T11:49:03Z

Motivation

DataTable's structure was purely visual: bare Views and TouchableRipples with no roles, indices or header relationships, so a screen reader conveyed no table context at all. A user heard "159" with no way to know it was the Calories column of row 3.

Changes

Web semantics: role="table" with aria-rowcount/aria-colcount, role="row" with aria-rowindex, role="columnheader" with aria-sort, role="cell" with aria-colindex.
Native fallback: table roles map to no accessibility trait on iOS or Android, so a row is announced as one item: "Dessert, Frozen yogurt, Calories, 159, row 3 of 6". It falls back to per-cell focus when a row holds interactive or non-text content, so nothing becomes unreachable. nativeFocusMode overrides the choice.
Non-actionable rendering: rows, cells and titles with no touch handler render a plain View.
Sort state: aria-sort on web, folded into the accessible name on native, with an announcement on change since focus stays on the header. New sortAccessibilityLabels localizes the wording.
Reanimated: the sort indicator moves off legacy Animated, matching Switch and Checkbox. Reduced motion is suppressed via ReduceMotion.Always instead of a manual snap, and 150ms becomes theme.motion.duration.short3 (same value).
Pagination: real control names, localizable through one labels prop. Data-dependent values are functions, so pluralization stays with the app's own i18n.
Columns: optional columns describes width and alignment once instead of repeating style on a title and every cell. New align composes with numeric, which is unchanged and not deprecated.
Text scaling: numberOfLines is honoured exactly at every font scale; the default is one line at the default scale and unclamped above it.
Tokens: separators move from surfaceVariant to outlineVariant, matching Divider.

Button gains aria-expanded, needed by the rows-per-page anchor which never reported that it opens a menu.

Breaking changes

Rows, cells and titles without a touch handler render a plain View. They lose the ripple, the web hover background and keyboard focus, and no longer report a disabled state.

// Before (v5): announced as a disabled control
<DataTable.Row>
  <DataTable.Cell>{item.name}</DataTable.Cell>
</DataTable.Row>

// After (v6): pass a handler if the row is meant to be pressable
<DataTable.Row onPress={() => select(item)}>
  <DataTable.Cell>{item.name}</DataTable.Cell>
</DataTable.Row>

Other important changes:

Rows are announced as a single item on native, and need rowCount and firstRowIndex for correct positions when paginating.
Pagination default labels changed, so tests querying the old placeholders need updating.
numeric now applies tabular figures, the one visual change to existing tables.

Related issue

Child of the "Modernize non-standard components" effort; no issue exists yet.

Test plan

yarn typescript, yarn lint clean
yarn test 806 passed, 167 snapshots. The 2828-line snapshot is replaced with 8 small per-component snapshots plus named contract assertions, since the old blob is where the aria-disabled regression sat unnoticed.
Web: verified against the live accessibility tree. Correct roles, counts and indices, aria-sort cycling, and no aria-disabled on any row, cell or title.
Android: TalkBack on an emulator, cross-checked with adb shell uiautomator dump. Tapping a row focuses that row, each header is its own stop, and a row containing an interactive element (e.g. Checkbox) falls back to per-cell focus.
iOS: Accessibility Inspector against the Simulator.
Reduced motion, 200% font scale, and RTL mirroring.

Screenshots:

JKobrynski · 2026-09-01T08:59:31Z

+  const publish = useLatestCallback(() => setHeaderLabels?.(labels));
+  const signature = labels.join(' ');
+
+  React.useEffect(publish, [publish, signature]);


Publishing the column names through an effect makes the table's ARIA indices a second-render value. Server-rendered output (the docs site is one, rspress.config.ts:122 aliases to react-native-web) gets aria-rowcount="6" instead of 7, and the header row and the first data row both get aria-rowindex="1" - duplicate row indices. DataTable already reads column position from ColumnIndexContext without an effect; can the header names go the same way?

JKobrynski · 2026-09-01T09:02:33Z

+  const label =
+    ariaLabel ?? (isWeb ? undefined : composeCellLabel({ columnLabel, value }));


Try const label = ariaLabel ?? (cellIsFocusUnit ? composeCellLabel({ columnLabel, value }) : undefined) - a cell wrapping a Checkbox currently gets aria-label="Pick", which buries the checkbox's own role and state behind the column name.

JKobrynski · 2026-09-01T09:05:36Z

+      'aria-rowindex':
+        index == null ? undefined : index + 1 + (table?.hasHeader ? 1 : 0),
+    }),
+    accessible: accessible ?? (rowIsFocusUnit || undefined),


Try accessible: accessible ?? rowIsFocusUnit - the || undefined leaves the prop unset, which is exactly when Pressable applies its own default of true, so a pressable row swallows the Checkbox inside it on iOS.

JKobrynski · 2026-09-01T11:09:58Z

+      return child.props.index === undefined
+        ? React.cloneElement(child, { index: firstRowIndex + offset })
+        : child;
+    });


Try the provider pattern you already wrote for columns (DataTableColumnsContext.tsx:36-44) - cloneElement means a consumer's <NameRow /> wrapper gets no index and silently loses its aria-rowindex. It is also the React.Children problem #4954 names.

oleksandrzavarzin-callstack · 2026-09-01T14:41:32Z

@JKobrynski Thank you for the review!
I've pushed the fixes to all of your comments. Please review the PR again

JKobrynski · 2026-09-02T13:50:40Z

+): child is React.ReactElement<P> =>
+  React.isValidElement(child) &&
+  typeof child.type !== 'string' &&
+  'displayName' in child.type &&


A fragment child crashes the table - <DataTable><>{rows}</></DataTable> throws
Cannot use 'in' operator to search for 'displayName' in Symbol(react.fragment) on this line, and so does a fragment inside DataTable.Row or DataTable.Header. It renders fine on main. Same family as #4710.

JKobrynski · 2026-09-02T13:51:11Z

+        // Anything else is taken for a row. Virtualized rows have no children
+        // here to number, so those pass `index` themselves.
+        return (
+          <RowIndexContext.Provider value={firstRowIndex + rendered++}>


Wrap the rows in a View and they all get the same aria-rowindex, because every child that isn't the header or the pagination counts as one row here. A <Text> empty state inflates aria-rowcount the same way, and the spoken "row 3 of 6" with it. Could rows register themselves instead, so only real rows are counted?

Thank you! I fixed your both moments.

The child map is now a recursive walk: rows are numbered wherever they sit, and
anything the table can see into - a fragment, a grouping View, a <Text>
empty state - is descended into rather than counted.

Not registration because a row can only claim an index by mutating shared state
during render, which double-counts under StrictMode, or in an effect - which
your DataTableHeader comment rightly ruled out for the server-rendered docs.

Have you tried a Divider between the rows with TalkBack? I'm afraid it counts as a row, so everything after it is announced one place too far.

Ok, I've added a divider to a skip list, the list of elements that won't be counted as a row.

JKobrynski · 2026-09-02T13:53:10Z

+    // Native has no column-header semantics, so a title that is not already a
+    // pressable has to opt in, or its text is absorbed by whichever ancestor
+    // happens to be focusable and the columns read as one run-on stop.
+    accessible: Platform.OS === 'web' ? undefined : true,


A header cell holding a select-all checkbox becomes one accessibility element on native, so the checkbox can't be reached - accessible is true here whatever the title contains. The row has a describable check for exactly this case; the title has none.

JKobrynski · 2026-09-02T13:53:50Z

+  ...rest
+}: Props) => {
+  if (
+    __DEV__ &&


This warning throws a ReferenceError in any web bundle that doesn't define __DEV__, and it is the first use of it in src/. splitStyles.ts:26 guards with process.env.NODE_ENV !== 'production' - worth matching that?

oleksandrzavarzin-callstack · 2026-09-03T11:19:38Z

@JKobrynski, your comments should be resolved now. Please check if that's true, and let me know if you have any additional issues here.

JKobrynski · 2026-09-04T11:44:44Z

+
+          // Anything the table can see into is descended into, not counted:
+          // a wrapper must not make its rows one row, nor an empty state a row.
+          if (nested !== undefined) {


A row component that takes children is now looked through instead of counted, so
<MyRow>{item.name}</MyRow> loses its aria-rowindex and the table under-counts. One using React.Children.only throws outright, where it renders fine on main. Both worked before this commit - since registration is out, is there another way to tell a grouping wrapper from a row component?

Thank you for pointing on it. The check is now the element's type plus what the table can see inside it.

The walk descends only into a type it sees through (Fragment, View, ScrollView, Text) or an element with a Header, Row or Pagination somewhere inside. Anything else counts as one row, as on main, so <MyRow> keeps its aria-rowindex.

Still one case, like on main: a wrapper whose rows the table can't see counts as one row. In this case index on the row is the way out. I've noted it in the migration doc.

JKobrynski · 2026-09-04T11:45:08Z

+    (typeof type === 'function' ||
+      (typeof type === 'object' && type !== null)) &&
+    'displayName' in type &&
+    (type as { displayName?: unknown }).displayName === displayName


Do we really need to use as here?

No, I've removed the cast.

…essibility-for-DataTable

JKobrynski · 2026-09-15T13:00:22Z

+          if (isTransparentContainer(child) || containsTableStructure(nested)) {
+            return nested === undefined
+              ? child
+              : React.cloneElement(


Any reason to rebuild every consumer's element here .github/instructions/code.instructions.md asks to avoid cloneElement and React.Children.

Oh, sorry. I haven't seen these instructions. I removed the cloning alltogether.
And now:

Fragment is flatten.

Text is left alone.

A View or a consumer wrapper is now rendered as written. A row that ends up with no position warns in dev. The migration guide notes the change.

Have you tried rows inside a View with VoiceOver now? I'm afraid they're still counted in the total but announce no position at all.

Unfortunately, I don't see a way to automatically insert an index without injecting it via cloneElement or similar implementations. That's why I've added a note to the migration guide and a warning about manual position inclusion (in dev mode). So the result code could look something like that:

<DataTable> <DataTable.Header>…</DataTable.Header> {pinned.map((item) => ( <DataTable.Row key={item.key}>…</DataTable.Row> ))} <ScrollView> {/* the consumer adds the offset */} {items.map((item, i) => ( <DataTable.Row key={item.key} index={pinned.length + i}>…</DataTable.Row> ))} </ScrollView> </DataTable>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

…essibility-for-DataTable

satya164 · 2026-10-22T18:19:24Z

Review by Claude

iOS

Wrapped cell text aligns to the wrong side in RTL.

Steps: turn on RTL in the drawer. In DataTableExample.tsx, rename Cupcake to a long name and pass numberOfLines={2} to the name cell. Open Data Table.

What happens: the two lines of the name start at the left edge of the column, while the single-line Eclair sits at the right. The wrapped Calories per piece header has the opposite problem: its lines align right inside an end-aligned column.

What should happen: start-aligned text aligns right in RTL, and end-aligned text aligns left. The web build renders both correctly.

(via Claude, verify if it makes sense)

Android

The same steps give the same result as on iOS. The wrapped name aligns left and the wrapped header aligns right.

(via Claude, verify if it makes sense)

satya164

Review by Claude

See the inline comments. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+        React.Children.map(nodes, (child) => {
+          if (!React.isValidElement<{ children?: React.ReactNode }>(child)) {
+            return child;
+          }
+
+          // Read before the guards below narrow `child` to `never`.
+          const {
+            type,
+            props: { children: nested },
+          } = child;
+
+          if (
+            isDataTableElement<DataTableHeaderProps>(child, 'DataTable.Header')
+          ) {
+            hasHeader = true;
+            columnLabels = readColumnLabels(nested);
+            return child;
+          }
+
+          if (isDataTableElement(child, 'DataTable.Pagination')) {
+            return child;
+          }
+
+          if (isDataTableElement(child, 'DataTable.Row')) {
+            return number(child);
+          }
+
+          if (isNeverRow(child)) {
+            return child;
+          }
+
+          if (type === React.Fragment) {
+            return walk(nested);
+          }
+
+          if (isGroupingContainer(child) || containsTableStructure(nested)) {
+            void walk(nested);
+            return child;
+          }
+
+          // What is left renders out of sight - a row component of the
+          // consumer's own, most often - so it counts as one row. A row the
+          // table never sees at all, as a virtualized list renders, passes
+          // `index` itself.
+          return number(child);


The cloning is gone, but the table still walks its children with React.Children.map and decides what each element is from its type and displayName. The project rules ask to avoid this, and it breaks as soon as a consumer wraps a part of the table in a component of their own:

const MyHeader = () => <DataTable.Header>...</DataTable.Header> is counted as a data row. On iOS the only row reads "Frozen yogurt, 159, row 2 of 2" and has no column names, because the header is never found.

const MyPagination = () => <DataTable.Pagination ... /> is counted as a row too. One data row reads "row 1 of 2", and aria-rowcount on web is 3.

Both render fine and the dev warning does not fire, so nothing tells the consumer. Could the table take this from explicit props instead? rowCount on the table and index on the row already exist, and a hasHeader-style prop or a label on each columns entry can cover the rest through context. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+export const readColumnLabels = (
+  children: React.ReactNode
+): Array<string | undefined> => {
+  const labels: Array<string | undefined> = [];
+
+  React.Children.forEach(children, (child, position) => {
+    labels[position] = isDataTableElement<LabelledProps>(
+      child,
+      'DataTable.Title'
+    )
+      ? getElementLabel(child.props)
+      : undefined;
+  });
+
+  return labels;
+};


Column names come from reading DataTable.Title elements by displayName, so a title in a wrapper loses its name. With const SortTitle = (props) => <DataTable.Title {...props} /> as the first column, the row reads "Frozen yogurt, Calories, 159, row 1 of 1" and the "Dessert" column name is gone. DataTableRow has the same problem at line 145: it reads child.props of each cell, so a wrapped DataTable.Cell makes the row fall back to per-cell focus.

Since columns is already the single place for column data, a label field on DataTableColumn, read through ColumnsContext, would give cells their column name without reading elements. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+export const withColumnIndices = (children: React.ReactNode) =>
+  React.Children.map(children, (child, index) =>
+    child == null ? (
+      child
+    ) : (
+      <ColumnIndexContext.Provider value={index}>
+        {child}
+      </ColumnIndexContext.Provider>
+    )
+  );


React.Children.map does not look inside fragments, so cells given in a fragment all get index 0:

<DataTable.Row> <> <DataTable.Cell>Frozen yogurt</DataTable.Cell> <DataTable.Cell>159</DataTable.Cell> </> </DataTable.Row>

With the example's columns, the second cell gets flex: 2 and start alignment from column 0. Both cells get aria-colindex="1" on web, and on iOS both are named after the first column ("Dessert, 159"). The cell's column key avoids this, so resolving cells by that key when columns is given would avoid both the positional guess and React.Children. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+        textAlign:
+          align === 'center' ? 'center' : isEnd === isRTL ? 'left' : 'right',


This flips the alignment twice on iOS and Android. React Native already mirrors left and right in RTL layouts there. Wrapped start-aligned text ends up on the left in RTL, and wrapped end-aligned text on the right. Only the web needs the mapping:

// iOS and Android mirror left and right in RTL layouts. The web does not. const mirror = Platform.OS === 'web' && isRTL; textAlign: align === 'center' ? 'center' : isEnd !== mirror ? 'right' : 'left',

The test "mirrors text alignment in right-to-left layouts" runs as iOS and currently asserts the double flip, so it needs to change with this. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+  const rotation = useSharedValue(sortDirection === 'ascending' ? 0 : 180);
+  const isFirstRender = React.useRef(true);

-  React.useEffect(() => {
-    spin.value = withTiming(sortDirection === 'ascending' ? 0 : 180, {
-      duration: 150,
-      easing: Easing.inOut(Easing.ease),
+  const { duration, easing } = theme.motion;
+
+  const timingConfig = React.useMemo(
+    () => ({
+      duration: duration.short3,
+      easing: Easing.bezier(...easing.standard),
      reduceMotion: reduceMotion ? ReduceMotion.Always : ReduceMotion.Never,
-    });
-  }, [reduceMotion, sortDirection, spin]);
+    }),
+    [duration.short3, easing.standard, reduceMotion]
+  );

-  const animatedStyle = useAnimatedStyle(() => ({
-    transform: [{ rotate: `${spin.value}deg` }],
-  }));
+  React.useEffect(() => {
+    if (isFirstRender.current) {
+      isFirstRender.current = false;
+      return;
+    }
+
+    rotation.value = withTiming(
+      sortDirection === 'ascending' ? 0 : 180,
+      timingConfig
+    );
+  }, [sortDirection, rotation, timingConfig]);


The arrow rotation is a transition between two states driven by sortDirection, so it fits Reanimated CSS transitions, as in Badge and Checkbox. That also removes the shared value, the effect and the isFirstRender ref:

<Animated.View style={[ styles.icon, { transform: [{ rotate: sortDirection === 'ascending' ? '0deg' : '180deg' }], transitionProperty: 'transform', transitionDuration: reduceMotion ? 0 : duration.short3, transitionTimingFunction: cubicBezier(...easing.standard), }, ]} > ``` (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+  const role =
+    Platform.OS === 'web'
+      ? ('columnheader' as const)
+      : onPress
+        ? ('button' as const)
+        : undefined;


On web a sortable title is a focusable div with role="columnheader". Screen readers announce it as a header, not as something to activate, and Space does nothing. Only Enter toggles the sort, because React Native Web activates on Space only for button roles. The ARIA sortable table pattern keeps columnheader on the container and puts a button inside it. Rendering a View with role="columnheader" around a Pressable with role="button" on web would fix both. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+    role:
+      Platform.OS === 'web' || !interactive
+        ? ('row' as const)
+        : ('button' as const),


A pressable row on web is a focusable role="row", so it has no activatable role and Space does not press it (only Enter does). A row in a table cannot also be a button. Interactive rows need either the grid pattern or a control inside a cell. (via Claude, verify if it makes sense)

satya164 · 2026-10-22T18:20:15Z

+<DataTable columns={columns}>
+  <DataTable.Title>Dessert</DataTable.Title>
+  <DataTable.Cell>{item.name}</DataTable.Cell>
+</DataTable>


This example puts DataTable.Title and DataTable.Cell directly in DataTable. With this PR the title is then counted as a row. A complete structure shows the change better:

Suggested change

<DataTable columns={columns}>

<DataTable.Title>Dessert</DataTable.Title>

<DataTable.Cell>{item.name}</DataTable.Cell>

</DataTable>

<DataTable columns={columns}>

<DataTable.Header>

<DataTable.Title>Dessert</DataTable.Title>

</DataTable.Header>

<DataTable.Row>

<DataTable.Cell>{item.name}</DataTable.Cell>

</DataTable.Row>

</DataTable>

``` (via Claude, verify if it makes sense)

oleksandrzavarzin-callstack added 5 commits August 26, 2026 17:18

refactor(data-table): add accessibility and column primitives

e7390ef

feat(button): expose aria-expanded

40fd57b

feat(data-table): expose table structure to assistive technology

5e94593

fix(data-table): give pagination controls real accessible names

5909225

doc(data-table): update migration docs

71f79a7

oleksandrzavarzin-callstack marked this pull request as ready for review August 28, 2026 13:52

JKobrynski reviewed Sep 1, 2026

View reviewed changes

fix(data-table): adress the pr comments

a91122e

JKobrynski reviewed Sep 2, 2026

View reviewed changes

satya164 added the Contributor: Internal label Sep 3, 2026

fix(data-table): count only real rows and survive fragment children

33d651f

JKobrynski reviewed Sep 4, 2026

View reviewed changes

oleksandrzavarzin-callstack added 3 commits September 4, 2026 17:06

fix(data-table): tell a row component from a wrapper by its type

59302c0

Merge remote-tracking branch 'upstream/main' into feat/structural-acc…

6d3780c

…essibility-for-DataTable

fix(data-table): keep pressable-only props out of the emitted types

20bc409

JKobrynski reviewed Sep 15, 2026

View reviewed changes

satya164 requested a balanced review from Copilot September 15, 2026 20:32

Copilot AI reviewed Sep 15, 2026

oleksandrzavarzin-callstack added 4 commits September 16, 2026 09:42

fix(data-table): leave wrapper as written instead of cloning

607a423

Merge remote-tracking branch 'upstream/main' into feat/structural-acc…

e53c7ba

…essibility-for-DataTable

fix(data-table): omit a divider between rows from counting as a row

c7eebe8

Merge remote-tracking branch 'upstream/main' into feat/structural-acc…

3c0d158

…essibility-for-DataTable

satya164 reviewed Oct 22, 2026

View reviewed changes

		const label =
		ariaLabel ?? (isWeb ? undefined : composeCellLabel({ columnLabel, value }));

		textAlign:
		align === 'center' ? 'center' : isEnd === isRTL ? 'left' : 'right',

Conversation

oleksandrzavarzin-callstack commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Breaking changes

Related issue

Test plan

Screenshots:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oleksandrzavarzin-callstack commented Sep 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oleksandrzavarzin-callstack commented Sep 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

satya164 commented Oct 22, 2026

iOS

Android

Uh oh!

satya164 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

oleksandrzavarzin-callstack commented Aug 28, 2026 •

edited

Loading