[table] Improve a11y for the pagination buttons by silviuaavram · Pull Request #49112 · mui/material-ui

silviuaavram · 2026-09-08T08:40:22Z

I have followed (at least) the PR section of the contributing guide.

Wrap buttons in Tooltip

Replace native title hints on TablePaginationActions with Tooltip so action labels appear on hover and keyboard focus.

Restore focus when buttons become disabled

When a focused action becomes disabled, move focus to the nearest enabled action instead of losing it to the document body. For example, navigating to the last page moves focus from Next to Previous. The search also handles actions disabled independently through slotProps and respects focus moved elsewhere by the application.

Preserves accessible labels, custom titles, button slots, refs, and RTL behavior.

code-infra-dashboard · 2026-09-08T08:42:49Z

Deploy preview

docs/data/material/components/table/table.md

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+901B^(+0.17%)	🔺+309B^(+0.20%)
@mui/lab	0B^(0.00%)	0B^(0.00%)
@mui/private-theming	0B^(0.00%)	0B^(0.00%)
@mui/system	0B^(0.00%)	0B^(0.00%)
@mui/utils	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Check out the code infra dashboard for more information about this PR.

Copilot

🔵 Needs a closer look

It changes focus-management behavior in a core component and should get final human validation across real-world browser/AT scenarios despite the added tests.

Pull request overview

This PR updates TablePaginationActions to replace native title attributes with MUI Tooltip for action labels and adds focus management so keyboard focus moves to the nearest enabled pagination action when the currently focused action becomes disabled.

Changes:

Wrap pagination action buttons with Tooltip while preserving aria-label behavior, RTL slot mapping, and slot customization.
Add layout-effect-based focus recovery when a focused action becomes disabled (including via slotProps).
Expand unit/browser-only coverage for tooltip visibility, slot/title preservation, and focus management scenarios.

File summaries

File	Description
packages/mui-material/src/TablePaginationActions/TablePaginationActions.js	Replace native titles with `Tooltip`, add focus tracking + focus relocation when a focused action becomes disabled, and preserve slot/ref behavior.
packages/mui-material/src/TablePaginationActions/TablePaginationActions.test.js	Add tests for tooltip behavior (hover/focus), custom slot/title preservation (LTR/RTL), and non-jsdom focus management behaviors.

Review details

Suppressed comments (1)

packages/mui-material/src/TablePaginationActions/TablePaginationActions.js:162

getItemAriaLabel('last', page) is currently evaluated in the slotProps destructuring even when showLastButton is false, which does extra work for a button that won’t render. Guarding the default initializer avoids calling getItemAriaLabel when the last button is hidden.

  const { title: lastButtonTitle = getItemAriaLabel('last', page), ...lastButtonSlotProps } =
    (isRtl ? slotProps.firstButton : slotProps.lastButton) ?? {};

Files reviewed: 2/2 changed files
Comments generated: 1
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Copilot

🟡 Changes recommended

Custom function slots without forwarded refs break tooltip display and focus restoration on supported React versions.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files reviewed: 2/2 changed files
Comments generated: 1
Review effort level: Balanced

mnajdova

Can we just show one Tooltip at a time? If one button is focused and the other hovered they overlap. I know in Base UI we have this feature about tooltip provider, I don't remember if we have something similar in Material UI, or if it is easy to achieve. If not, let's add comment to fix this in the next major once we migrate the Tooltip to Base UI.

mnajdova · 2026-09-09T09:27:45Z

+import useForkRef from '../utils/useForkRef';
 import { getTablePaginationActionsUtilityClass } from './tablePaginationActionsClasses';

+function isDisabled(button) {


I can see this logic in other places too, could be useful to have it extracted in @mui/material/utils so potentially it can be reused.

I couldn't find other places, found a couple which partially use some of it, but that's it.

mnajdova · 2026-09-09T09:30:09Z

+    other.onBlur?.(event);
+  };
+
+  useEnhancedEffect(() => {


Let's add a comment what the effect is about.

Copilot

🟡 Changes recommended

The generated PropTypes additions need corresponding TypeScript declarations and regeneration.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files reviewed: 3/3 changed files
Comments generated: 1
Review effort level: Balanced

Copilot

🟡 Changes recommended

A nullish custom aria-label can now leave an action without an accessible name.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files reviewed: 3/3 changed files
Comments generated: 1
Review effort level: Balanced

mnajdova · 2026-09-11T07:44:51Z

+    }
+
+    // Prefer following actions, then fall back to preceding actions in reverse order.
+    const nextButton = [...buttons.slice(index + 1), ...buttons.slice(0, index).reverse()].find(


Much simpler 👌

mnajdova

Logic looks good, I left few comments on improving the docs. Please resolve them before merging.

mnajdova · 2026-09-11T07:45:51Z

 ### Custom pagination actions

 The `ActionsComponent` prop of the `TablePagination` component allows the implementation of custom actions.
+A replacement action component is responsible for its own tooltips and focus management, unless it composes the built-in `TablePaginationActions` component.


Suggested change

A replacement action component is responsible for its own tooltips and focus management, unless it composes the built-in `TablePaginationActions` component.

The replacement action component is responsible for its own tooltips and focus management, unless it composes the built-in `TablePaginationActions` component.

mnajdova · 2026-09-11T07:46:59Z

+The default buttons include tooltips.
+When replacing `firstButton`, `previousButton`, `nextButton`, or `lastButton` through `slots.actions`, the custom component receives a `title` prop and is responsible for rendering its own tooltip.
+
+When an update to pagination props or action slot props disables the focused action, `TablePaginationActions` moves focus to the next enabled action in DOM order, or searches backward if none follows.


Suggested change

When an update to pagination props or action slot props disables the focused action, `TablePaginationActions` moves focus to the next enabled action in DOM order, or searches backward if none follows.

When an update to pagination props or action slot props disables the focused action, `TablePaginationActions` moves focus to the nearest enabled action in the DOM order.

mnajdova · 2026-09-11T07:48:01Z

+Actions with `tabIndex={-1}` are skipped.
+Focus stays where it is if no action is available or your application has already moved focus elsewhere.
+
+Custom button slots participate in focus restoration by forwarding the supplied `data-mui-pagination-action` prop to their focusable element.


Suggested change

Custom button slots participate in focus restoration by forwarding the supplied `data-mui-pagination-action` prop to their focusable element.

In order for custom button slots to participate in focus restoration you need to pass the `data-mui-pagination-action` prop to their focusable element.

Maybe also list the available values for it, as they are not documented anywhere at this moment.

silviuaavram requested review from ZeeshanTamboli and siriwatknp and a lite review from Copilot September 8, 2026 08:40

silviuaavram added accessibility a11y scope: table Changes related to the table. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. labels Sep 8, 2026

Copilot started reviewing on behalf of silviuaavram September 8, 2026 08:40 View session

Copilot AI reviewed Sep 8, 2026

View reviewed changes

Comment thread packages/mui-material/src/TablePaginationActions/TablePaginationActions.js Outdated

silviuaavram force-pushed the fix/table-actions-a11y-improvements branch from 59d49d8 to fba526f Compare September 8, 2026 13:41

silviuaavram requested a balanced review from Copilot September 9, 2026 06:45

Copilot started reviewing on behalf of silviuaavram September 9, 2026 06:46 View session

Copilot AI reviewed Sep 9, 2026

View reviewed changes

Comment thread packages/mui-material/src/TablePaginationActions/TablePaginationActions.js Outdated

mnajdova reviewed Sep 9, 2026

View reviewed changes

silviuaavram requested a balanced review from Copilot September 9, 2026 15:46

Copilot started reviewing on behalf of silviuaavram September 9, 2026 15:47 View session

Copilot AI reviewed Sep 9, 2026

View reviewed changes

Comment thread packages/mui-material/src/TablePaginationActions/TablePaginationActions.js

silviuaavram force-pushed the fix/table-actions-a11y-improvements branch from 410002f to 7ef866a Compare September 10, 2026 08:28

silviuaavram requested review from mnajdova and a balanced review from Copilot September 10, 2026 08:28

Copilot started reviewing on behalf of silviuaavram September 10, 2026 08:29 View session

Copilot AI reviewed Sep 10, 2026

View reviewed changes

Comment thread packages/mui-material/src/TablePaginationActions/TablePaginationActions.js

mnajdova reviewed Sep 11, 2026

View reviewed changes

mnajdova approved these changes Sep 11, 2026

View reviewed changes

silviuaavram force-pushed the fix/table-actions-a11y-improvements branch from ecff5e7 to d15266c Compare September 11, 2026 13:19

silviuaavram added 5 commits September 14, 2026 12:35

wrap action buttons in tooltips

3d1b621

restore focus whenever pagination button becomes disabled

98a6b18

pnpm proptypes

d8dff4a

keep tooltip for now

6f0f56f

add back focus restorration

c13c9ec

silviuaavram added 4 commits September 14, 2026 12:35

update the docs

5face8a

try a waitFor in test

5579be8

improve effect comment

4be1fce

keep aria label when title is passed

f089ea2

silviuaavram force-pushed the fix/table-actions-a11y-improvements branch from d15266c to f089ea2 Compare September 14, 2026 09:35

silviuaavram merged commit 7b06515 into mui:master Sep 14, 2026
22 checks passed

	A replacement action component is responsible for its own tooltips and focus management, unless it composes the built-in `TablePaginationActions` component.
	The replacement action component is responsible for its own tooltips and focus management, unless it composes the built-in `TablePaginationActions` component.

	When an update to pagination props or action slot props disables the focused action, `TablePaginationActions` moves focus to the next enabled action in DOM order, or searches backward if none follows.
	When an update to pagination props or action slot props disables the focused action, `TablePaginationActions` moves focus to the nearest enabled action in the DOM order.

	Custom button slots participate in focus restoration by forwarding the supplied `data-mui-pagination-action` prop to their focusable element.
	In order for custom button slots to participate in focus restoration you need to pass the `data-mui-pagination-action` prop to their focusable element.

Uh oh!

Uh oh!

Conversation

silviuaavram commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Wrap buttons in Tooltip

Restore focus when buttons become disabled

Uh oh!

code-infra-dashboard Bot commented Sep 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Bundle size

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Suppressed comments (1)

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

mnajdova left a comment

Choose a reason for hiding this comment

Uh oh!

mnajdova Sep 9, 2026

Choose a reason for hiding this comment

Uh oh!

silviuaavram Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Sep 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

mnajdova Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova left a comment

Choose a reason for hiding this comment

Uh oh!

mnajdova Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

mnajdova Sep 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

silviuaavram commented Sep 8, 2026 •

edited

Loading

code-infra-dashboard Bot commented Sep 8, 2026 •

edited

Loading