Skip to content

List Tables: Keep columns readable with horizontal scrolling. - #13866

Open
mattmiklic wants to merge 36 commits into
WordPress:trunkfrom
mattmiklic:improve/list-table-overflow
Open

mattmiklic wants to merge 36 commits into
WordPress:trunkfrom
mattmiklic:improve/list-table-overflow

Conversation

@mattmiklic

@mattmiklic mattmiklic commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

List tables can squeeze columns into an extremely narrow state when they need more space than the table has available. Plugins that add columns can leave little room for content like post titles, producing tall rows that are difficult to scan.

This adds a scrollable wrapper around the existing table. Above the existing mobile breakpoint, tables switch from fixed to automatic layout, with minimum widths for selected Core columns. When the columns exceed the available space, the wrapper scrolls horizontally. Filters, bulk actions, and pagination stay outside the wrapper.

The table's border moves to the new wrapper, and a fade to white inside it indicates that there is hidden content on the right edge. When scrolling, the fade appears on the left as well, when content is hidden on that edge. These are reversed for RTL content. JavaScript in common.js updates the fades during scrolling, resizing, and when tables are replaced or refreshed in place, like when searching Plugins.

When there is horizontal scrolling, the wrapper enters the Tab order so it can be focused and scrolled with the arrow keys. When a table's content fits in the viewport, the wrapper isn't included in the Tab order.

Screenshots

Many columns

With enough columns enabled, titles and headers become difficult to read. The updated table ensures readable column widths and scrolls to reveal the remaining content.

Before After
Posts table with plugin columns squeezing titles into narrow vertical stacks Posts table with readable titles and a right-edge fade indicating more columns

Columns that fit without scrolling

With fewer columns visible, the table fits without horizontal scrolling. Automatic layout gives the date column more room, reducing wrapping and row height in this example.

Before After
Posts table with dates wrapping onto three lines and taller rows Posts table fitting within the viewport, with dates wrapping onto two lines and more rows visible

Content that prevents wrapping

Preformatted text, text forced onto one line, or a fixed-width widget previously overflowed outside their column, colliding with the content in any that follow. Now, that column expands to contain whatever is in it, and the horizontal scrolling contains it.

Before After
Comments table with non-wrapping text and a fixed-width widget overlapping adjacent columns and overflowing the page Comments table containing wide content within a horizontally scrollable viewport, with other columns beyond its right edge

Testing

The included tests cover initialization, LTR/RTL scrolling, fractional positions and overscroll, resizing, keyboard focus, and cleanup when tables or wrappers are replaced or moved.

To test in the admin:

  1. Open Posts with enough visible columns enabled to crowd the table. Size the window larger than the mobile breakpoint, and confirm the columns remain readable as the table begins to scroll.
  2. Scroll to both ends and confirm each fade appears only when content is hidden on that side. Repeat in an RTL locale.
  3. Tab to an overflowing wrapper and scroll with the arrow keys. Check that a table which fits does not add a Tab stop, and that sorting links retain a complete focus indicator.
  4. Resize below the mobile breakpoint and check the existing mobile layout remains unchanged.

Trac ticket: https://core.trac.wordpress.org/ticket/52151

Use of AI Tools

AI assistance: Yes
Tool(s): Codex (ChatGPT)
Model(s): GPT-6 Astra
Used for: Developing and iterating on the implementation, writing regression checks and documentation, researching browser support, and assisting with code review.


This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

Wrap list tables in a named, keyboard-focusable scrolling region and apply minimum widths to desktop text columns. Keep the outer border on the viewport and retain the existing mobile layout.
Retain the existing Comments column width as a desktop minimum so automatic table layout cannot shrink the header enough to wrap its sort arrows.
Overlay a subtle shadow at the inline end of desktop list-table viewports while content remains beyond that edge. Use a scroll-driven CSS animation so the shadow disappears at the end and stays hidden when the table fits. Preserve the existing layout in browsers without support and at mobile widths.
Control the edge shadow through native scroll and resize handling in `common.js` so it no longer depends on CSS scroll-driven animation support. Track right-to-left positions and refresh observers when AJAX replaces a table, while preserving the existing desktop layout and mobile styles.
Show a shadow at each edge when table content is hidden beyond it, including right-to-left layouts. Clamp scroll positions so fitting tables and elastic overscroll do not produce misleading shadows, and suppress horizontal rubber-banding with `overscroll-behavior-x: none` on the desktop wrapper.
Cover initialization, LTR and RTL scroll boundaries, resizing, and cleanup after table replacement. Exercise `common.js` through dedicated QUnit fixtures for normal and minified builds.
Replace edge shadows with full-height buttons that scroll to adjacent columns. Keep their chevrons centered in the visible table area, respect reduced-motion preferences, and return focus to the table when a focused control reaches its boundary.

Extend the QUnit coverage for directional paging, labels, focus handling, icon positioning, and cleanup after table replacement. Preserve the existing mobile layout.
Draw focus indicators inside sortable links so the scroll viewport does not clip them. Move the high-contrast outline inward as well.
Keep list table wrappers in the tab order only when they provide horizontal scrolling. Preserve existing focus when overflow disappears, and restore the original `tabindex` attribute when overflow tracking ends.

Add regression coverage for resizing, focus retention, visible overflow, and cleanup.
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Core Committers: Use this line as a base for the props when committing in SVN:

Props mattmiklic, mciampini, westonruter, joen, jameskoster.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@github-actions

Copy link
Copy Markdown

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

  • All changes will be lost when closing a tab with a Playground instance.
  • All changes will be lost when refreshing the page.
  • A fresh instance is created each time the link below is clicked.
  • Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
    it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

@jasmussen

Copy link
Copy Markdown

This has kept coming up for me constantly over the years, I've multiple friends and family I've helped with website, they install a single plugin and on their 14 inch laptops, their columns implode. A contextually available scrollbar feels like such a better choice.

I would love if folks could give deep reviews of this one so we can land it. If not in 7.2 then 7.3—it's been an issue for a while and it's worth going straight at it.

Comment thread src/wp-admin/css/list-tables.css Resolved

@ciampo ciampo left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have further feedback, although I'd feel safer if other folks tagged for review also gave it a look.

@jasmussen

Copy link
Copy Markdown

I would love to start with the forced wrapping, and then we can respond to issues raised by plugins that inject HTML there, perhaps. It's ideally going to land early in 7.3 so there will be plenty of surface area to test.

On the shadow, if you feel strongly, I'll personally support you. A quick ping to @jameskoster though, I think as we chatted about this he suggested the white.

@jameskoster

Copy link
Copy Markdown

I think the fade works better when it matches the row background. Like this:

fade

I appreciate this maybe to expensive to justify though.

In lieu of that I have no strong feelings on fade vs shadow.

Remove generated content scrollers and their bookkeeping, relying on CSS wrapping for preformatted text and preserving plugin-owned scrolling markup. Update the regression tests to cover the simplified behavior.

Match edge fades to Core row backgrounds and keep them aligned with the scrolling viewport. Remove the opacity transitions.
Use sticky CSS fades so they stay at the viewport edges during fast scrolling, and preserve column alignment for editing rows. Keep comment Quick Edit within the visible width and prevent sorting icons from extending the scrollable area beyond the table.

Remove obsolete comment-content wrapper selectors and add LTR/RTL regression coverage for spanning edit rows and the comment editor.
@mattmiklic

mattmiklic commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor Author

Thanks @jasmussen and @jameskoster.

I would love to start with the forced wrapping, and then we can respond to issues raised by plugins that inject HTML there, perhaps. It's ideally going to land early in 7.3 so there will be plenty of surface area to test.

Totally fair; I was solving for plugins that could cause excessive wrapping, but I'm fine with taking a simpler approach and expanding if it's needed. I backed out the in-cell content wrapping JS, but left the pre wrapping as it was just two lines of CSS.

I think the fade works better when it matches the row background.

I didn't think this was possible, but I had an agent give it another try and it worked fine. Also works on the yellow cells for unapproved comments.

Screenshot 2026-10-26 at 5 00 15 PM

These changes have been committed and pushed to the branch if you want to take another look.

Comment thread src/wp-admin/css/list-tables.css Resolved
Give the generated fade cells a nonzero border in the row background color so WebKit paints their border images. Preserve the zero-width columns and existing fade appearance.
@mattmiklic

Copy link
Copy Markdown
Contributor Author

@westonruter just for awareness -- based on the feedback from @jasmussen I removed the in-cell scrolling when there's plugin-generated wide content in a comments row. The logic is that it's enough of an edge case to leave out unless we discover a real-world case where it's an issue -- the cases I designed for initially were theoretical. There should be plenty of time for this to be tested and iterated upon if it's needed. Let me know if you disagree or have any other feedback here!

@jasmussen
jasmussen requested a review from a team November 12, 2026 09:35
@jasmussen

Copy link
Copy Markdown

I'd love to get this in as early as possible in the 7.3 cycle, so I pinged a few folks! Thank you all for looking.

@jrfnl
jrfnl removed the request for review from a team November 12, 2026 13:20
oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 16, 2026
Match the fade on the wp-admin list tables (WordPress/wordpress-develop#13866), so both tables show the same cue.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 16, 2026
Add a sticky fade cell at the start of every row, mirroring the one at the end of tables without actions, so the columns scrolled past the start fade into the row's background as on the wp-admin list tables (WordPress/wordpress-develop#13866). At the start of the scroll range the cell only covers its own space, so it needs no scroll state.

The cell is as wide as the first column's start padding and takes its place, so the first column stays where it was. It is narrower than the trailing fade for that reason. The header button of the first column pulls back by its own padding to keep its label lined up with the cells. The cell gets its own column in the colgroup so the column widths do not shift, and sits below the sticky header.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 17, 2026
Match the fade on the wp-admin list tables (WordPress/wordpress-develop#13866), so both tables show the same cue.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 17, 2026
Add a sticky fade cell at the start of every row, mirroring the one at the end of tables without actions, so the columns scrolled past the start fade into the row's background as on the wp-admin list tables (WordPress/wordpress-develop#13866). At the start of the scroll range the cell only covers its own space, so it needs no scroll state.

The cell is as wide as the first column's start padding and takes its place, so the first column stays where it was. It is narrower than the trailing fade for that reason. The header button of the first column pulls back by its own padding to keep its label lined up with the cells. The cell gets its own column in the colgroup so the column widths do not shift, and sits below the sticky header.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 18, 2026
Match the fade on the wp-admin list tables (WordPress/wordpress-develop#13866), so both tables show the same cue.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 18, 2026
Add a sticky fade cell at the start of every row, mirroring the one at the end of tables without actions, so the columns scrolled past the start fade into the row's background as on the wp-admin list tables (WordPress/wordpress-develop#13866). At the start of the scroll range the cell only covers its own space, so it needs no scroll state.

The cell is as wide as the first column's start padding and takes its place, so the first column stays where it was. It is narrower than the trailing fade for that reason. The header button of the first column pulls back by its own padding to keep its label lined up with the cells. The cell gets its own column in the colgroup so the column widths do not shift, and sits below the sticky header.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Use a 24px gradient at each overflowing edge so row backgrounds and dividers help reveal hidden content. Remove the per-row fade-color overrides.
@mattmiklic

Copy link
Copy Markdown
Contributor Author

I've updated this PR to match the implementation from (WordPress/gutenberg#86829), with a 24px fade and extending the fade to the dividers between rows as well.

@jasmussen @jameskoster this led me to revisit one question. I'd previously made the text fade but not the row background color, which aesthetically looked nicer but has the problem of not clearly indicating there's hidden content when there's not content visibly being clipped by the edge. For that reason I returned to the fade to white. Let me know if you have differing opinions though.

Posts

Before After
Posts before Posts after

Comments

Before After
Comments before Comments after

@jasmussen

Copy link
Copy Markdown

I like the after, even if it's a subtle change. But I also think it's one of those things where this is worth shipping, because there's always another train for iterating based on feedback.

.wp-list-table-scroll > .fixed .column-slug *,
.wp-list-table-scroll > .fixed .column-locations,
.wp-list-table-scroll > .fixed .column-locations * {
overflow-wrap: anywhere;

@ciampo ciampo Nov 19, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've been testing some edge cases and discovered this:

A long URL in a category description widened the whole table and pushed Slug and Count offscreen. (At a 1,280px viewport, adding https://example.test/resource/ followed by 192 hex characters took the table from 693px to 2,172px.)

I saw the same issue with a long email address on Users. Could we extend the wrapping rule to .column-description and .column-email, and add a test with a long URL?

</tfoot>

</table>
<div class="wp-list-table-scroll" role="region" aria-label="<?php echo esc_attr( $table_label ? $table_label : __( 'Items list' ) ); ?>" tabindex="0">

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Installed Plugins, searching for Akismet changed the region's accessible name from “Plugins list” to “Items list”. Could the AJAX response reuse the label from the initial page so the landmark keeps its name after a search?

Comment thread tests/qunit/wp-admin/js/common.js Outdated
frame.onload = resolve;
} );
const stylesheet = new URL( '../../src/wp-admin/css/list-tables.css', document.baseURI );
frame.srcdoc = '<!DOCTYPE html><html dir="' + direction + '"><head><link rel="stylesheet" href="' + stylesheet.href + '"><style>.column-score a { display: inline-block; padding: 8px 0 8px 11px; }</style></head><body style="font: 13px sans-serif">' + this.wrapper.outerHTML + '</body></html>';

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional test coverage

The fades looked right in Chromium and WebKit. While checking them, I noticed the RTL fixture sets dir="rtl" and loads the LTR stylesheet, but the rule that mirrors the fades relies on the admin body's .rtl class. Could we use the RTL stylesheet and body class here and check which edge shows the fade?

oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 19, 2026
Match the fade on the wp-admin list tables (WordPress/wordpress-develop#13866), so both tables show the same cue.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
oandregal added a commit to WordPress/gutenberg that referenced this pull request Nov 19, 2026
Add a sticky fade cell at the start of every row, mirroring the one at the end of tables without actions, so the columns scrolled past the start fade into the row's background as on the wp-admin list tables (WordPress/wordpress-develop#13866). At the start of the scroll range the cell only covers its own space, so it needs no scroll state.

The cell is as wide as the first column's start padding and takes its place, so the first column stays where it was. It is narrower than the trailing fade for that reason. The header button of the first column pulls back by its own padding to keep its label lined up with the cells. The cell gets its own column in the colgroup so the column widths do not shift, and sits below the sticky header.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Allow URLs in descriptions and email addresses to wrap without pushing neighboring columns offscreen. Set the Plugins screen reader headings when preparing the list so live search returns the same accessible name as the initial page.

Exercise overflow fades with the generated RTL styles and compare inline editing rows with the outer edges of the columns they span.
@mattmiklic

Copy link
Copy Markdown
Contributor Author

@ciampo thanks for the review! Good catches. I've just pushed these changes:

  • Long URLs in category descriptions and long email addresses on Users now wrap.
  • Plugins live search preserves the “Plugins list” screen-reader label.
  • Added regression tests for both fixes. The fade tests now use the admin’s RTL stylesheet and check the left and right edges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants