[Proposal] Focus Traversal API

I am beginning to come around on this, but let me ask you this… does calling focus() on an element actually imply that focus will be received by said element or is it just a request. I think the answer to that question dictates whether or not Async is needed for calls like forward() and backward(). If there is a garauntee of focus getting received, then sure, async might be in order. But if it’s more of just a request, then sync is fine.

Also, another thought, but what happens if you call focus() a second time while waiting for the first focus() to resolve? If the resolve condition of focus is the focus event and that never occurs, how would we know?


Here’s what I’m understanding of HTMLElement.focus() (which could be awry, so grain of salt.)

  1. Check a flag to prevent running focus on an element it is already running on. If true, return to prevent overlap.
  2. Set the flag mentioned previously to true.
  3. Focusing Steps run, which I believe at the end of it all (assuming the element is validly focusable) it forces the element to receive focus.
  4. Unset the flag from step 1 so a new focus call can succeed.

For more info you can see the WhatWG spec on focus requirements. I don’t see how it being required or a request is the linchpin of it being async or not though. The async APIs can always verify the state at the end and return an indicator true/false as to whether the request to focus succeeded or not.

And the flag mentioned in the focus steps clears up what happens if it is called multiple times on an element before one finishes resolving. It just returns and does nothing on subsequent calls.

I think the question of async/sync comes down to whether or not the focusing steps have async behaviors in them (i.e. does any of the focus steps have an async nature). What caught my in in the spec regarding this was this:

User agents must immediately run the focusing steps for a focusable area or browsing context candidate whenever the user attempts to move the focus to candidate.

Which seems to imply a syncronous nature (i think).

Another similar work: https://github.com/medialize/ally.js

1 Like

So what is the next step for moving forward on this? Whom do I need to contact? How does this process work from here?

I think a good next step would be to create a GitHub repository for the proposal and write an explainer for it.

An example: https://github.com/bokand/root-scroller/blob/master/explainer.md

1 Like

Sounds good. I will work on it over he next few days. Some questions:

1). Can I use the current polyfill repo which already has the proposal in it? 2). What do I do once the explainer is done?



Sure, just an explainer.md file in the project’s root directory should be fine.

Once the document is ready for feedback, don’t hesitate to contact the relevant people directly (e.g., accessibility experts) to get their opinion on the proposed API.

1 Like

Yeah! And dont forget to ping this thread when ready! Excited to see what you come up with!

1 Like

An EXPLAINER for the FocusTraversal API is now available at https://github.com/awesomeeng/FocusTraversalAPI/blob/master/EXPLAINER.md.

Comments and feedback welcome.

Also, suggestions on next steps welcome. In particular, how do we get the EXPLAINER in front of the correct eyeballs?


You could contact people on Twitter, which is probably the most popular social network among the people who participate in the standardization process. Try searching Twitter for posts that are related to your proposal. Just earlier today, the HTML spec editor from Google posted about trying to tackle various focus issues: https://mobile.twitter.com/domenic/status/1126686171017416704.


Yes, what @simevidas said , or in the gh itself https://github.com/whatwg/html/issues/4607 too

1 Like

@simevidas @briankardell thank you both for pointing me at that. I replied both on twitter and GH.

Also, generally I am really bad at signal boosting, which is partly why I offered the proposal here as this discourse is in theory supposed to get the proposal in front of the right eyes. Unfortunately, I’m not sure it does, thus my reason for asking for suggestions on how to get more eyeballs.

At one point I thought I read something about being able to request a mentor for your ideas here, but never been able to find that again. Would if I could.


You’ll also want to coordinate with the people at CSS WG who are working on the Spatial Navigation API. Their spec talks about a general next/previous focus traversal as a possible extension.


1 Like

@AmeliaBR: Thank you for the heads up! I posted over on their issues and await further contact.

1 Like

I’ll be speaking about the Focus Traversal API Proposal at JSCONF US 2019 next week (August 12 2019 @2:15pm, Track B). Hope to see some of you out there and talk more about making focus better!

Do you have a link to that issue? There are many things related to focus - it seems to me that if you want to make some new API you could either find an existing thing that it is developing where it might potentially ‘fit’ and likely make small adaptation requests — or you can pursue this as it’s own thing. If the latter, a good step would be to try to get this to advance this to an actual incubation which requires some support for solving your explainer problems, and that they aren’t better solved via some other existing (potentially developing) effort. If you’d like to understand this more, you can feel free to reach out to me and I can try to help explain more.

1 Like

The issue over at CSSWG is at https://github.com/w3c/csswg-drafts/issues/3944

The issue over at WHATWG/HTML Spec is at https://github.com/whatwg/html/issues/4784

I would love to talk to you more about what to do. My understanding with the WHATWG is I have to convince one of the browser manufacturers to implement it, which I have no idea how to do.

Check out this document from Google on how they are looking to help incubate new ideas. It outlines the process overview and provides a link to the explainer example to fill out to get the ball rolling.


This is a tremendous find. Thank you! I will look into it a lot more.