Why Keyboard Users Can’t Scroll Your Overflow Containers

So, you build a data table with long rows, lots of columns, and horizontal scroll on the container. It works fine with a mouse and you ship it.

But! When a keyboard user Tabs into the table, its focus lands on a cell. Then they press the arrow keys to read across the row but nothing happens. They try Tab again, but this time it jumps to the next interactive element entirely outside the table. The rest of the content is there and screen reader users can navigate it just fine, but there is no way to scroll the container without a mouse.

You may have never noticed this because you most likely only test with a mouse. Your screen reader users never noticed because they navigate the accessibility tree, not the scroll container. The only person it traps is the sighted keyboard user and most teams never test for that.

I didn’t either, until someone filed a bug I couldn’t reproduce until I put my mouse away.

Focus Management and Scroll Containers Are Not the Same Thing

Keyboard focus follows tab order. The tab order then follows interactive elements, like buttons, links, inputs — basically anything the browser considers actionable. That’s the system the spec built for keyboard navigation.

Scroll containers are a completely different system because they are layout primitive. What I mean by that is the browser handles overflowing content in different ways any time you set overflow to auto, scroll, or hidden on an element. The browser’s job is to manage overflowing content, not necessarily navigate it. The spec never classified overflow as interactive.

The gap between those two systems is where keyboard users fall through.

This is not a browser bug. Every major browser behaves identically here because they are all following the same spec and the scroll container and focus management are both doing their jobs, although they were not designed to work together.

The CSS Properties That Create Scroll Containers Without Warning

I briefly mentioned a few overflow property values that affect the way overflow is handled, but which values actually create scroll containers? auto is the obvious one, but the scroll containers have a habit of appearing where you least expect them.

For example, it’s worth remembering that overflow is a shorthand. And it’s a little weird how the constituents work. Like, setting the overflow-x constituent to auto to handle horizontal overflow implicitly sets overflow-y to auto. So, a container you’re managing for horizontal scrolling is also a vertical scroll container, and keyboard users can’t scroll either axis without a mouse.

/* This: */
.table-wrapper {
  overflow-x: auto;
}

/* ...is the equivalent of this: */
.table-wrapper {
  overflow-x: auto;
  overflow-y: auto;
}

The same thing happens with overflow: hidden which most developers use it to clip content or clear floats. It might not be obvious, but hidden still creates a scroll container. The content is clipped, not gone (which could be an accidental form of “data loss”), and keyboard users can still focus into it; they just can’t scroll to any of it.

There are less obvious triggers, too. More properties like transform, filter, perspective, will-change (referencing transform), contain (set to paint), and content-visibility (set to auto) all create scroll containers. You may have added one of these for a performance optimization or an animation and quietly created a keyboard trap at the same time.

/* Added for a smooth animation */
.panel {
  transform: translateZ(0);
  overflow: hidden; /* clipping the content */
}

/* Result: .panel is now a scroll container
    keyboard users can focus into it but can't scroll it */

One of the reasons this bug ships so often is that the scroll container wasn’t intentional and nobody audited it because nobody knew it was there.

The Fix

The “fix” is adding tabindex="0" to the scroll container in the markup:

<div class="scroll-container" tabindex="0">
  <!-- scrollable content -->
</div>

That puts the container in the tab order so keyboard users can now Tab to it. And once it has focus, the arrow keys scroll it. The browser handles the rest.

But that is only part of the fix. Adding tabindex without an accessible name means a screen reader encounters a focusable element with nothing to announce. A plain div with tabindex="0" has no name, and the screen reader says nothing useful. You need to add an aria-label that describes what the container holds.

​​role="region"​ and aria-label​ work together. The role tells assistive technology this is a landmark region. The label is what gets announced when focus lands on it. Without the label, screen readers announce”region” and nothing else. That tells the user nothing about what they’re about to scroll through.1

<!-- This is too vague -->
<div
  class="scroll-container"
  tabindex="0"
  aria-label="scrollable"
  role="region"
>
  <!-- scrollable content -->
</div>

<!-- This is more descriptive -->
<div
  class="scroll-container"
  tabindex="0"
  aria-label="Monthly sales data, scrollable"
  role="region"
>
  <!-- scrollable content -->
</div>

Another common problem when working with scroll containers that need to support keyboard tabbing is using visible and obvious focus styling. It’s common to see outline: none or outline: 0 as a design requirement. But then the container is selectable, but invisible. Keyboard users will land on it with no clear indication. Focus styles are indeed style-able, so we can still make then obvious and attractive if the design calls for something custom:

.scroll-container:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

The outline color doesn’t need to match your brand exactly, It just needs a two-color combination to ensure contrast with all components, per WCAG’s techniques:

When tabindex="0" Isn’t the Answer

Making a scroll container focusable isn’t always the right call.

If you can’t write a clear and useful aria-label for the container, that’s a signal the content might need restructuring rather than an interactive patch. A scroll container that wraps a single image, a decorative element, or content that’s already fully reachable by tab order doesn’t need to be in the tab order itself. Putting it there adds noise without adding value.

​​That said, if a container holds a large number of focusable items, fifty links in a sidebar or a long list of cards, a single Tab stop on the wrapper may actually be preferable to forcing keyboard users through every item individually. The trade-off shifts when the list is long enough that tabbing through it becomes its own burden. In those cases, tabindex="0"​ on the container is the right call even if the items inside are already focusable.

The harder call is when every item inside already has independent keyboard interaction, e.g., a list of buttons, set of links, or a group of form fields. All of these are already in the tab order so users can reach each one with Tab. If the container is just a visual wrapper around already-accessible content, making the wrapper focusable means users have to Tab through one extra stop to get to the things they actually want to interact with.

The test I run is a simple one. Something like can a keyboard user reach every piece of meaningful content inside the container without tabindex="0" on the wrapper? If yes, skip it. If no, add it.

When the right answer is skipping tabindex, restructuring the DOM is usually the better path. Breaking up long content, splitting it across sections, or using a disclosure pattern with progressive reveal often solves the problem at the layout level without creating accessibility compromise.

How to Audit This

The keyboard-only walkthrough is the fastest test. Unplug or disable your mouse, open the page, and press Tab through every interactive element and every scrollable container. If you reach a container with overflow content and can’t scroll it with the arrow keys after tabbing to it, it needs fixing. On most pages, this would only take about five minutes and the bugs are usually obvious the moment you stop using a mouse.

Note: ​​One thing worth being clear about is that this article is desktop-focused. Virtual keyboards on iOS and Android interact with scroll containers differently, and touch navigation has its own set of considerations. If mobile keyboard accessibility is a concern for your project, that warrants its own investigation.

Chrome’s accessibility panel gives you a structural view. Open DevTools, go to the “Accessibility” tab, and inspect a scroll container. If it shows no role and no accessible name, it’s invisible to assistive technology as a navigable element. That’s a quick way to confirm whether a container needs tabindex="0" and aria-label before you touch the code.

Tools like Deque’s Axe-core and WAVE can automatically catch some of these issues. For Axe-core specification you can use the scrollable-region-focusable rule to flag scroll containers that have focusable content but are not themselves focusable. Running axe-core in your CI pipeline means this class of bug gets caught before it reaches production rather than after a user files a ticket.

// axe-core in a Jest test
import axe from 'axe-core';

test('scroll containers are keyboard accessible', async () => {
  const results = await axe.run(document.body, {
    rules: { 'scrollable-region-focusable': { enabled: true } }
  });
  expect(results.violations).toHaveLength(0);
});

One thing axe-core misses is containers that have overflow content but no focusable children. Those won’t trigger the rule because there’s nothing to Tab into. The keyboard walkthrough catches these cases but the automated tool does not.

How I Approach This Now

Here are the three questions I ask myself:

1. Does the scroll container hold content that can’t otherwise be reached by keyboard**?** That’s stuff like a data table, a code block, a chat log or a custom carousel — basically anything where the only way to see all the content is to scroll. If the answer is yes, add tabindex="0", an aria-label, and a visible :focus-visible style. All three together. Not just the attribute.
2. Can every piece of meaningful content inside be reached by **Tab** without scrolling? If the container wraps a list of links or a group of buttons, the content is already keyboard-accessible. That is, unless there’s visually hidden content due to overflow. If the container has overflow content that’s not visually visible but is in tab order, users still need a way to scroll to see it. Making the wrapper focusable adds tab stops without adding access. Skip it.
3. Is the container the result of an unintentional overflow trigger from transform, contain, or similar? If you added a property for reasons unrelated to scrolling and it created a scroll container as a side effect, consider removing the property if you can, or add tabindex="0" only if there’s content that genuinely needs it.

That’s the whole decision tree. The fix is simple once you know the container exists, but the hard part is knowing it’s there. That’s what the keyboard walkthrough is for.

The Test That Changes How You Build

The keyboard walkthrough takes no more than five minutes but most developers never run it because they assume their users use a mouse. Most of them are correct, most of the time. But the sighted keyboard user is real, and they’re using your product right now, and they’ve quietly learned which interfaces to avoid because they’re not worth the frustration.

Using tabindex="0" won’t fix everything. It won’t fix a poorly structured DOM, a missing accessible name, or a focus style that was stripped out in a global CSS reset. But it closes the gap between what looks accessible and what actually is, and it costs almost nothing to add.

The thing I keep coming back to is that this bug is invisible to the developer, invisible to the screen reader user, and invisible to automated testing until you configure it specifically to look. The only way to find it is to use the product the way the affected user does, which is the test so put your mouse away.

Further Reading

• Keyboard-Only Scrolling Areas (Adrian Roselli)
• When to Use tabindex=”0″ (Graeme Coleman)
• Short Note on Improving Usability of Scrollable Regions (SteveFaulkner)
• A Guide to Designing Accessible, WCAG-Conformant Focus Indicators (Sara Soueidan)
• Indicating Focus to Improve Accessibility (Hidde de Vries)

---

Why Keyboard Users Can’t Scroll Your Overflow Containers originally handwritten and published with love on CSS-Tricks. You should really get the newsletter as well.

from CSS-Tricks https://ift.tt/q0fsMnV
via IFTTT