Focus management RFC

[devongovett]

This is an RFC for an RFC (ooh so meta 🤯). I'd like to get feedback from the React core team and the community on whether this is something that React should even handle before I do the work to come up with an API and write a formal RFC. Please let me know what you think!

Focus management

Focus management is the programmatic movement of keyboard focus in an application in response to user input, such as mouse, touch, or keyboard interactions. Implementing keyboard support for components and applications is imperative for accessibility, and not enough web applications implement this properly today. See the ARIA Practices document for more information about focus management and keyboard interfaces.

In React, implementing many common components is very easy, but implementing those components with proper support for accessibility and focus management is still quite difficult. Applications that do implement support typically use a component library which has taken the time to get this right. However, implementing such a library correctly is very challenging and time consuming, and I think React could enable library authors to handle focus management in an easier way.

Challenges

I work on the React implementation of our design system at Adobe. One of our main jobs is to implement a component library with proper support for accessibility, and we have faced some challenges while trying to achieve this goal.

Refs Everywhere

Refs are meant as an escape hatch from the declarative React model to make things happen imperatively, but we've ended up having one or more in almost every component in our library. The main reason we have refs is for focus management. We need to focus particular elements in response to events like keyboard navigation with arrow keys, etc. In addition, sometimes we need to find children of refs with querySelector and other DOM methods in order to focus the correct elements, e.g. elements inside child components. This feels pretty unclean, and un-reacty to us and I think there could be a more declarative API that React could enable.

Global focus state

The imperative focus management API in the DOM is global: only one element can be focused at a time. Calling node.focus() immediately causes all other nodes to lose focus, and the new node to gain focus. Therefore, components basically fight one another for focus. In reusable components, this is a challenge since they don't know what other components are on a page. There is no way for a component to "remember" what was focused before, so that focus can be restored to it later without some manual work in every component. This will be described more below in some of the other sections. I think React components could potentially do this automatically.

Roving tab index

Keyboard users typically navigate between components with the tab key, which changes the focused element. However, composite components such as lists, grids, trees, etc. should only appear in the tab sequence in an application once. It would be annoying if you had to tab through every item in a long list just to get past the entire list to the next element afterward. Therefore, you tab to the list, and if you want to navigate within the list you use the arrow keys, and otherwise you can tab to the next element after the entire list.

The roving tab index pattern is one way to solve this problem, but basically it involves each component being able to "remember" what was focused last, so that if a user tabs away from a list and then back, the list item they were on before is re-focused rather than the first item or the list itself. I think a focus management API in React could potentially help make this problem easier to solve.

Focus Trapping

Focus trapping is important for modals and other popups. It prevents users from tabbing or focusing elements outside a particular region. For example, if a user tabs to the last element in a modal dialog, when they hit tab again the first element of the dialog should be focused instead of something outside. This is currently impossible to implement in a general way in React without manual DOM querying and imperative focusing. I think a focus management API in React could help solve this.

Restoring focus

When you close a dialog or popover, focus should be restored to whatever had focus before the modal opened. This requires us to remember what was focused last, and when the component unmounts focus that element again. I think this should also happen automatically.

Why should this be in React?

We have experimented with various abstractions to make the above easier in user space, but have come to the conclusion that it would be better implemented in React itself. I haven't come up with an exact API that I think React should adopt yet (the purpose of this issue is to get feedback first), but generally, I think components should have a notion of whether they are in focus, and should be able to declaratively specify which of their child elements should have focus, and lock focus to within the component subtree. This has turned out to be difficult to implement in user space without access to the full React tree (only direct component children).

Most of the above points talked about the web, but I think an API in React core for this could be useful for other targets as well, such as React Native. React Native also has imperative APIs for focus management at the moment I think, so perhaps this could be valuable there as well.

Additionally, making implementation of proper accessibility patterns much easier for the entire React community could have a huge effect on the quality of modern web applications. Not everyone is using a component library that has invested as much time as we have into supporting accessibility. If more of this happened in React itself, then there would be less work for library authors and more people would be able to put in the effort.

Thoughts?

Sorry for the long issue. If you have thoughts or feedback please let me know. Is this something the React team and community would be interested in? If so, I'll work on an RFC for an API. If anyone else has ideas or has experience with this, please tell me in the comments!

[oriSomething]

Related even if limited:

• https://github.com/theKashey/react-focus-lock
• https://ui.reach.tech/alert-dialog
• https://material.angular.io/cdk/a11y/overview (Angular take)

Personally, it seems more specifically ReactDOM related. Not sure if it means ReactDOM's components, hooks or imperative API.

[theKashey]

Don’t forget about portals, which does break some ”dom” assumptions. While it still possible to support them somehow, as long as focus and blur events bubbles thought React tree - you can’t “tab” into them.

Related: facebook/react#14540

[jquense]

@devongovett I'd be interested in what you think (broadly) such an abstraction or api would look like. I've also spent a lot of time building ui primitives in React (react-bootstrap, react-widgets, etc) and my experience definitely matches yours that focus management is hard and puts you soundly in ref-land everywhere. I've been mostly under the impression tho that browsers don't really offer the low level api's to do it well.

Maybe said another way, almost all my attempts to do broad focus management have resulted in very specific solutions for the use cases, because all of the imperative involvement needed to probably move and "stick" focus. I haven't had a sense that React knows more than i can about where focus is or should be, so while i'd love to see this in react, it's unclear to me whether React can help.

The other component here is the potential cost of such an abstraction. My experience as an app and library builder is that nitty-gritty focus mgmt is something most done in libraries. It's terrible and bad, but generally isolated, e.g. keeping focus in the right place inside a custom date-picker etc. Similarly focus trapping is annoying but solvable as a util, and with portals its easier b/c at least now focus bubbles up the react tree correctly for fixed position drop downs etc.

Sorry for the wall of text! This is something i think is super important and would love to see improvement on. I do think think we need to probably spec out what an API could look like and whether it's reasonable possible to implement. I also know the @sebmarkbage has had some thoughts around this in the past (i believe i'm remembering that correctly)

[devongovett]

Personally, it seems more specifically ReactDOM related. Not sure if it means ReactDOM's components, hooks or imperative API.

Yep, react-dom would definitely be involved here, but I think the API could possibly be shared with other targets like react-native as well, which also supports focus.

Don’t forget about portals, which does break some ”dom” assumptions.

Good point. I think a react focus manager could possibly make that work correctly.

[devongovett]

I'd be interested in what you think (broadly) such an abstraction or api would look like.

Ok, so this isn't very well thought through yet, but I think generally that components, along with elements, should have a notion of whether they are focused or not, i.e. conceptually there should be an activeComponent within React kinda like document.activeElement. They should be able to declaratively specify one of their child elements as "focused", whether or not the element actually has DOM focus. This would allow components to only need to worry about managing focus for their direct children, and not the rest of the world (see global state section above). The actual focused DOM element would be the focused element of the focused component.

This would also solve the issue of "remembering" what was focused last within a composite component (e.g. list) when tabbing to it or otherwise restoring focus. Additionally, when a component unmounts which currently has focus, focus could be restored to the previous component that had focus, and therefore to the correct child element (e.g. closing a dialog).

Along with a declarative API for specifying which child of a component should be focused, the API should allow for some common things:

• Focusing a specific element.
• Locking focus within a component's boundaries.
• Restoring focus when a component unmounts.
• Moving focus to the previous, next, first, or last focusable element (i.e. in response to the arrow or tab keys)

Those have been the main patterns we've needed to solve. There may be others, but I think those would get us a long way.

Again, people have implemented all of this in userland before using DOM APIs, but people had also implemented UIs before React. I think React could allow for a better API to make this easier and less bug-prone, like it did for the rest of UI development, which is why I'm proposing this as a feature. This is one of the last main things we have to go directly to the imperative DOM APIs for, and I find it unfortunate when the rest of React is so nice to work with.

[jamiebuilds]

To get an API discussion started (Edit: Sorry the above comment hadnt loaded when I posted this), can anyone identify a primitive which might make implementing focus management significantly easier which is more generic than focus management itself?

What's the minimal missing piece of React which would make this problem space easier?

[devongovett]

Thinking about this more, I think there is a conceptual focus tree that should exist. At the root is a FocusScope, which can contain FocusNodes and other FocusScopes. FocusNodes are elements which can be focused (e.g. input, button, select, etc.). These nodes form an ordered list within a FocusScope, which is used when tabbing around with the keyboard. Only nodes within the currently focused scope can be tabbed to. A FocusScope retains the state for its currently focused node even when it is not focused. When a focused scope is destroyed, it's parent scope becomes focused, and that scope's focused node receives focus.

As an example, imagine a page with a button which opens a dialog when clicked. Initially, focus is on the root scope, so you can tab around and get to the button. When the dialog is opened, the root scope loses focus, and the dialog's scope receives focus. You can tab around within the dialog, but not outside. When the dialog closes, and the scope is destroyed, the parent scope (root) becomes focused and focus is restored to the button.

This could be modeled in React like this:

function Dialog() {
  return (
    <FocusScope>
      <div className="dialog">
        <FocusNode><input placeholder="input 1" /></FocusNode>
        <FocusNode><input placeholder="input 2" /></FocusNode>
      </div>
    </FocusScope>
  );
}

It's almost possible to implement this using React context. You store the tree of scopes on the context, and FocusNodes register themselves with the nearest scope.

The problem with that, and the reason I think this should be part of React itself, is that focusable elements should automatically register as FocusNodes with the nearest scope, i.e. you shouldn't have to wrap them in <FocusNode> manually. Otherwise, we could use FocusNode in our component library's Textfield component, but if a user just used <input> manually then it wouldn't be focusable since the focus scope wouldn't know about it.

The best option would be if React by default registered the root focus scope on the page, and also exposed the <FocusScope> component for implementors of components like Dialog to register child scopes.

There also needs to be an API to control focus programmatically, but I haven't quite come up with that yet. It would involve possibly accessing the current focus scope and calling methods on it, e.g. FocusScope.current.focusNext() and FocusScope.current.focusPrevious(). I'm not really sure that's the best option though, and also haven't thought of a way to refer to a specific element to focus it other than refs...

[jamesplease]

You can tab around within the dialog, but not outside.

I’m not a fan of React core dictating this behavior: I dislike the accessibility consequences. When a dialog in this situation isn’t active, a user can tab their way right out of the app and into the browser chrome (in many popular browsers). When the dialog is active, it prevents this native behavior, locking the user into the app.

I know this is probably an unrealistic goal, but I’d prefer to see a new API added to browsers that add something like what you’re describing, but one that doesn’t “lock” users into the page.

[devongovett]

I dislike the accessibility consequences.

Ironic given that locking focus in a dialog is an accessibility feature to begin with. 😉 But, you're right, it's not ideal to prevent the user from tabbing out to the location bar or elsewhere. Perhaps there is a way to implement this so that can still be achieved, but even if not, I'd argue that preventing focus of other fields in the webpage e.g. behind the dialog is worse than not being able to tab out, which is why so many component libraries implement it this way.

I’d prefer to see a new API added to browsers that add something like what you’re describing

That would be awesome. I think we'd still need support from react though, in order to deal with things like Portals.

[jquense]

It's possible to implement focus trapping that mimics the native dialog behavior, at least closely. Userland modals tho do need to do something, it's much worse to have no trapping from an a11y perspective, (SRs also have there own shortcuts for escaping to browser chrome so it's not necessary the worst if focus doesn't cycle out to the chrome. That said there is a browser API inert tho I think it stalled getting standardized

[theKashey]

‘Inert’ could be emulated with ‘aria-hidden’ - reach/portal is doing that. But you have to know which nodes you shall hide - “your” nodes, including portaled ones, should stay.

That’s said - we need an DOM abstractions, we could traverse. ReactDOM tree representing hierarchy from React poi t of view, including even something not yet rendered in a concurent mode.

Meanwhile, this data structure already exists(“fiber”) and used by many tools. But yet not documented.

[AlmeroSteyn]

Love when accessibility features get this kind of attention!

My initial feelings echoes that of @jquense :

Maybe said another way, almost all my attempts to do broad focus management have resulted in very specific solutions for the use cases, because all of the imperative involvement needed to probably move and "stick" focus. I haven't had a sense that React knows more than i can about where focus is or should be, so while i'd love to see this in react, it's unclear to me whether React can help.

Focus management is there to repair the standard DOM focus when we disrupt it with our code. In most applications there should be very little of that. Mostly router related, focusing error texts, the odd WAI-ARIA widget (which should really be built and tested into a library) and the odd modal (although the prolific use of modals is just as big an a11y issue as focus management). This does get a lot more complex the more complex the interface gets, though.

But the idea that React may try to actually focus things makes me slightly edgy. Hijacking the user's intention could in some cases be worse than not managing focus at all. So any such system should be opt-in if it is to do any focus setting itself and configurable to act in only certain parts of the application.

Think, for example, of the router. Trying to set focus to the actual content which may still be lazy loading while React is already overriding this focus to a previous element.

Another thing is that SR users can jump to entire other blocks. ARIA landmarks like

and and are exposed as quick navs via the screen readers. We'd need to avoid a situation where focus management becomes a race condition between AT and React.

We'd also have to consider the fact that React bubbles the focus and blur events, unlike the actual DOM.

I do like the idea of things like focusNext and focusPrevious as that can be pretty nasty to calculate resulting in, as you say, a whole soup of refs. Also the idea of activeElement and then caching the last focussed element, maybe something like prevActiveElement. But these are also, in a sense, imperative calls and the last two can probably be solved with hooks.

You can tab around within the dialog, but not outside.

I’m not a fan of React core dictating this behavior: I dislike the accessibility consequences. When a dialog in this situation isn’t active, a user can tab their way right out of the app and into the browser chrome (in many popular browsers). When the dialog is active, it prevents this native behavior, locking the user into the app.

I'd think that if a modal is complex enough for the user to want to tab out of it, it should perhaps not be a modal at all. Modals represent a complete context switch to the user and SR users should know they are in a modal and why. And aside from focus management the entire page content underneath needs to be set to aria-hidden="true". If it is just a screen in screen inception then rather use a loaded view and keep the standard behaviour? Again, overuse of modals causes serious a11y issues.

I don't mean to come across as negative, really just stating what I've experienced. If there can be a solution to make focus management easier while not getting in the way that would be great. I just don't see a lot of solutions for the the issues I know about in the proposal yet.

[devongovett]

Focus management is there to repair the standard DOM focus when we disrupt it with our code. In most applications there should be very little of that.

Yeah, I think most users of React should never need to do their own focus management in application level code. Most of my job is implementing the ARIA widgets you mention though, so the main purpose of making a proposal for react core is to make this easier for us and other library authors. The easier this is to get right, the more libraries will do so.

But the idea that React may try to actually focus things makes me slightly edgy. Hijacking the user's intention could in some cases be worse than not managing focus at all.

I don’t think the intent is to take over the browser’s default focus management, but to allow an easier way for react components to move focus when it is actually warrented (see my original examples), and to make common patterns such as modals easier/possible to implement correctly (e.g. portals). We currently have to go to the native DOM APIs to do this, and that is hard to get right and feels dirty when the rest of react is so nice to work with.

[theKashey]

How "modals" were done in jQuery era

• for every focusable outside of the target, set tabindex=-1
• for every node, not containing target, set aria-hidden
• in other words - reverse inert.
  And that could not be inert, or any other DOM-based solution due to portals, at least.

Probably we should do the same thing - "ask" ReactDOM or ReactNavite to apply some behavior settings to a tree, outside of the marked location.
Could it be something like Suspense - a special component which would instruct React to do something somewhere inside, or outside it's boundaries.
But that something should not be bound to focus.

[mshoho]

I have been working on a similar thing for ReactXP library (https://github.com/Microsoft/reactxp). It has an ability to restrict focus inside some container (for modals), limit focusability inside some container (for the list items so that you don't tab through the list forever), arbitrate focus when there is more than one candidate to be focused (the focus redirects might break the announcement of modals as the screen reader reads the modal title only first time you get inside).

There is an updated approach in the works which I do as a standalone package and plan to if a tree won't fall on me eventually opensource. It might be not what you need exactly, but at least it'll be a place for dumping the experience. There are lots of things we are used to never consider.

Generally, if you plan to allow the design system consumers to write custom HTML, the odds that their application won't ever be stable accessibility-wise are very high. As one focusable/accessible component outside the managed set of components might break the whole thing. Also computing the accessibility tree, the browsers imply a lot (and sometimes change the logic of this implication).