[focusgroup] Add the focusgroup attribute by janewman · Pull Request #11723 · whatwg/html

janewman · 2025-09-29T21:16:04Z

This adds the focusgroup attributes needed to allow for declarative focus navigation using the directional navigation (arrow keys, d-pad).
This specs the behavior detailed in the explainer on OpenUI.

At least two implementers are interested (and none opposed):
- Chromium: ChromeStatus entry, implementation bug
- Mozzila Standards Position - positive
- Webkit Standards Position
Tests are written and can be reviewed and commented upon at:
- Mark as non-tentative once there is consensus: html/interaction/focus/focusgroup/tentative
Implementation bugs are filed:
- Chromium
- Gecko: …
- WebKit: …
Corresponding HTML AAM & ARIA in HTML issues & PRs:
MDN issue is filed: …
The top of this comment includes a clear commit message to use.

/dom.html ( diff )
/index.html ( diff )
/infrastructure.html ( diff )
/interaction.html ( diff )

…nts.

janewman · 2025-11-24T17:33:25Z

Opening up for review, but please keep in mind this is an early draft.

janewman · 2025-11-24T17:35:53Z

@annevk, during TPAC you expressed interest in taking a look at this draft spec change - I would really appreciate any feedback you had as I work to move this towards something we think accurately captures the behavior and fits in with the existing logic.
Thanks!

smaug---- · 2026-01-08T15:55:14Z

It is unclear to me what happens if the page has keydown, or keyup event listener and calls preventDefault() when arrow key is used. Which event listener has some affect and which doesn't?
What if some modifier is used with the key event?

…ng section, improve segment definition with example, and simplify key conflict element handling

janewman · 2026-02-02T23:30:18Z

It is unclear to me what happens if the page has keydown, or keyup event listener and calls preventDefault() when arrow key is used. Which event listener has some affect and which doesn't? What if some modifier is used with the key event?

I've added a new section that should answer all of these questions, please let me know what you thank and if it still isn't clear.
Thanks for all of the feedback, it is very much appreciated!!

…talled event See whatwg#12145 (comment) for context.

This change allows select elements with the multiple attribute to be rendered as a drop-down box when the author explicitly sets the size attribute to 1. The related issue should be resolved by suggesting that mobile browsers and desktop browsers both follow these rules in order to improve cross-platform compatibility. Fixes whatwg#8189.

This aligns `ancestorOrigins` exposure with referrer policy when using the `iframe referrerpolicy` attribute, so an embedder can prevent revealing its own origin to embedded documents. If an `<iframe>` uses `referrerpolicy="no-referrer"` or `same-origin` (and the parent and child are cross-origin), the parent’s origin and any same-origin ancestors are replaced with opaque origins (until reaching an ancestor that is cross-origin). Other policies continue to expose full origins. This approach keeps existing behavior by default (for web compat) while addressing privacy concerns with an opt-out. The algorithm reuses the parent's existing list of ancestor origins, avoiding synchronous cross-process lookups and ensuring a stable snapshot even if ancestors mutate their `referrerpolicy` attributes later. Fixes whatwg#1918. Closes whatwg#2480.

Instead of having a "scripting flag" and then "fixing" scripts in createContextualFragment(), change "scripting flag" to an enum for clarity.

See https://github.com/whatwg/spec-factory for details.

Currently per spec, #update-the-navigation-api-entries-for-a-same-document-navigation will be called in different order to the #wait-for-all navigation handler list depending on if the navigation is intercepted or not. This is not ideal, but even more so, in case of a "traverse" navigation, the callback passed to the #wait-for-all and the might be called before the call to #update-the-navigation-api-entries-for-a-same-document-navigation has happened. This means that we'll run the finish steps with the wrong session history entry. Since all same document navigations, intercepted or otherwise, eventually call #update-the-navigation-api-entries-for-a-same-document-navigation we can ensure that we never run the navigation handlers with bad state. This patch also reverts the patch that introduced always having a method tracker, since that was intended to solve this issue but failed doing so. Fixes whatwg#12222, fixes whatwg#12165. Reverts whatwg#11814.

* Markup: For some `data-x="attr-input-{max,min}"`, change `attr` to `concept` * Punctuation: Insert a couple periods * Punctuation: Change colon to period

…attribute Specify support for the loading attribute for the video element and audio element using similar conventions to img and iframe, where the attribute already has precedent. Loading has possible values of eager and lazy. When a media element's loading attribute value is lazy, loading of any video or poster image data, as well as autoplay playback, will defer until layout is known and the video is in the viewport. Fixes whatwg#10376 Fixes whatwg#6636

Fixes whatwg#11879.

Key changes: - Rename 'no-memory' token to 'nomemory' (unhyphenated, matching explainer) - Add 'nowrap' modifier token for explicitly disabling wrapping - Add default modifiers per behavior token (toolbar→inline, tablist→inline wrap, menu→block wrap, menubar→inline wrap) - Add default modifiers column to behavior tokens table - Add text explaining how default modifiers work and interact with explicit modifiers - Update ARIA Role Inference to document <button> child role inference eligibility (buttons are the most common composite widget item) - Add note that aria-orientation is not inferred from inline/block - Add note about reading-flow CSS property interaction with both sequential and directional navigation - Update directional navigation algorithm to reference effective modifiers (including defaults) - Update wrap check in navigation algorithm to account for nowrap and default modifiers - Replace toolbar example with proper tablist example showing default modifiers, focusgroupstart, child role inference, and tab panel association - Add menubar/menu nested focusgroup example demonstrating independent nested focusgroups with default axis/wrap behavior Co-authored-by: Copilot <[email protected]>

- Reword key conflict element definition to emphasize native/built-in arrow key behavior (UA-determined), not author-scripted handlers - Add note with author guidance for scripted key conflicts: use focusgroup='none', limit axis, or activation/escape pattern - Fix scrolling conflict scenario to reference key conflict escape behavior and clarify that only focusable scrollable regions (UA-determined) are affected Co-authored-by: Copilot <[email protected]>

# Conflicts: # source

janewman · 2026-04-15T18:34:26Z

@smaug----, @annevk, I would love to get your thoughts on the latest iteration, friendly ping for review, I appreciate your time.

When an element enters the document's top layer (e.g., a popover shown via showPopover(), a modal dialog, or a fullscreen element), exclude it and its shadow-including descendants from any ancestor focusgroup scope. Changes: - focusgroup scope: exclude top-layer elements and their shadow-including descendants (qualified so the owner's own focusgroup is unaffected) - focusgroup segment: top-layer subtrees create segment boundaries - entry element algorithm: last-focused-item is ineligible while its subtree is in the top layer - clearing conditions: exception preserves last-focused-item when scope exit is solely due to top-layer membership - new "Top layer interaction" section with normative prose and examples Co-authored-by: Copilot <[email protected]>

Align the top-layer segment boundary clause with the focusgroup="none" clause by requiring the top-layer element to be sequentially focusable. This matches the Chromium implementation, which only creates segment boundaries for excluded subtrees containing focusable content. Co-authored-by: Copilot <[email protected]>

annevk

I'm also missing the WebDriver integration piece.

annevk · 2026-04-24T18:41:53Z


  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLOrSVGElement" data-x="dom-fe-autofocus">autofocus</dfn>;
  [<span>CEReactions</span>, <span data-x="xattr-ReflectSetter">ReflectSetter</span>] attribute long <span data-x="dom-tabindex">tabIndex</span>;
+  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute DOMString <dfn attribute for="HTMLOrSVGElement" data-x="dom-focusgroup">focusgroup</dfn>;


Should this use DOMTokenList?

This is something I considered, but felt that the behavior-first ordering and modifier pattern felt like it might not fit into the patterns that other attributes that use DOMTokenList have today.

This is not a strong opinion, so if you feel that DOMTokenList is a much better fit for this use case, I'd be OK with changing this.

- Rename IDL properties: focusgroup → focusGroup, focusgroupStart → focusGroupStart - Rename concept terms: 'focusgroup item/owner/scope/segment' → 'focus group ...' - Revert wrong punctuation change (. not ;) in focusable area conditions - Replace 'store' with 'set' per spec conventions - Remove duplicate note about memory/focusgroupstart - Add cross-reference for 'set of space-separated tokens' - Add terminal punctuation on list items - Fix 'effective modifiers' cross-reference - Fix 'focus group owner of' data-x slug in algorithms - Move last focused item dfn to concepts section - Move domintro entries after their attribute dfns - Move focusGroupStart domintro to focusgroupstart section Co-authored-by: Copilot <[email protected]>

- Fix radiogroup/listbox default modifiers (wrap, block) - Add token case-sensitivity statement (ASCII case-insensitive) - Fix entry element top-layer check with owner-descendant qualifier - Disambiguate tabindex-ordered scope conjunction - Add clearing condition for focusgroup attribute removal - Fix tree order → shadow-including tree order - Add empty items guard in directional navigation - Fix toplayer parenthetical and Tab reachability explanation - Add AT browse mode note and aria-orientation example - Add missing 'then' in If-conditionals - Change ul to ul class=brief for key conflict list - Fix redundant key conflict element re-definition - Tighten focus group owner definition - Fix scope definition wording precision Co-authored-by: Copilot <[email protected]>

On macOS, Safari does not include button elements in the tab order by default without Full Keyboard Access enabled. Adding explicit tabindex="0" ensures the examples work cross-platform and matches the approach taken in the WPT tests. Co-authored-by: Copilot <[email protected]>

janewman · 2026-04-25T02:00:10Z

I'm also missing the WebDriver integration piece.

I'm still looking into what we can do here. Regarding having WebDriver toggle the MacOS keyboard setting, I've reached out to James Craig who I've worked with in aria and WPT regarding our options here, waiting to hear a response. In the meantime, I've adjusted all WPTs to accommodate, with all buttons having a tabindex of 0 manually set.

janewman added 9 commits October 7, 2025 22:54

Initial commit

0039b8f

correctly escape element names.

90f40d7

Add more examples and update behavior wrt conflicts and opt-out eleme…

5250133

…nts.

Update key-conflict element behavior.

fc2339b

Move concepts up above the table that references them.

ce67c0a

Formatting and clarity.

1b996a7

Quick pass on the directional navigation algorithm, still needs work.

cde7f45

Cleanup and clarifications.

8f0f3e5

Clarifications and reorganizing.

e852c96

janewman force-pushed the focusgroup branch from b998d1f to e852c96 Compare October 7, 2025 22:58

Memory should be per focusgroup, not per-segment.

8b9648b

janewman mentioned this pull request Oct 7, 2025

[focusgroup] Declarative directional focus navigation for composite widgets #11641

Open

janewman added 4 commits October 8, 2025 04:00

Move focusgroup under the focus section.

cb96e56

Update to match latest thinking.

cbbe6f8

Add definition for order-modified document order

7e5f089

Additional updates to match latest explainer and address feedback.

b782014

janewman mentioned this pull request Nov 7, 2025

WHATUP at TPAC 2025: agenda suggestions #11711

Closed

janewman marked this pull request as ready for review November 24, 2025 17:33

smaug---- reviewed Jan 8, 2026

View reviewed changes

Comment thread source Outdated

smaug---- reviewed Jan 8, 2026

View reviewed changes

Comment thread source Outdated

smaug---- reviewed Jan 8, 2026

View reviewed changes

Comment thread source Outdated

janewman mentioned this pull request Jan 13, 2026

[focusgroup] Rename focusgroup-entry-priority to focusgroupstart openui/open-ui#1356

Merged

janewman mentioned this pull request Jan 20, 2026

Incubation: Scoped Focusgroup w3ctag/design-reviews#1152

Open

4 tasks

lukewarlow mentioned this pull request Jan 21, 2026

focusgroup attribute WebKit/standards-positions#171

Open

Rename focusgroup-entry-priority to focusgroupstart, add Event Handli…

1017afb

…ng section, improve segment definition with example, and simplify key conflict element handling

janewman requested a review from smaug---- February 2, 2026 23:39

alastor0325 and others added 15 commits March 27, 2026 21:07

Editorial: clarify the difference between :stalled pseudo-class and s…

4f74971

…talled event See whatwg#12145 (comment) for context.

Editorial: replace scripting flag with a scripting mode enum

35f91e6

Instead of having a "scripting flag" and then "fixing" scripts in createContextualFragment(), change "scripting flag" to an enum for clarity.

Editorial: grandgrandchild is not correct English

b796eff

Meta: update repository files

d622fa4

See https://github.com/whatwg/spec-factory for details.

Meta: correct link to CONTRIBUTING.md in README

d3e204e

Don't prepare script for script elements when src attribute is removed

dc053ed

Editorial: fix misc. markup and punctuation

3196bba

* Markup: For some `data-x="attr-input-{max,min}"`, change `attr` to `concept` * Punctuation: Insert a couple periods * Punctuation: Change colon to period

Make topmargin and leftmargin attributes apply to both sides

f51af9f

Fixes whatwg#11879.

Meta: specify for attribute on structs that hold navigables

f98ba03

github-actions Bot mentioned this pull request Apr 1, 2026

focusgroup web-platform-dx/developer-signals#546

Open

janewman added 2 commits April 1, 2026 19:25

Merge remote-tracking branch 'origin/main' into focusgroup

aa58328

# Conflicts: # source

Another pass.

6b88453

janewman mentioned this pull request Apr 2, 2026

Focusgroup mozilla/standards-positions#1348

Closed

AutoSponge mentioned this pull request Apr 2, 2026

[focusgroup] clarify and handle cases where scrollable regions have focusgroups (accessiblity) w3c/a11y-tracking#190

Open

fix missing definition

07b7ded

janewman and others added 2 commits April 23, 2026 22:47

annevk reviewed Apr 24, 2026

View reviewed changes

janewman and others added 4 commits April 24, 2026 20:24

Simplify last-focused-item top-layer language

472c927

Conversation

janewman commented Sep 29, 2025 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

janewman commented Nov 24, 2025

Uh oh!

janewman commented Nov 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smaug---- commented Jan 8, 2026

Uh oh!

janewman commented Feb 2, 2026

Uh oh!

janewman commented Apr 15, 2026

Uh oh!

annevk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

annevk Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

janewman Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

janewman commented Apr 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

20 participants

janewman commented Sep 29, 2025 •

edited by pr-preview Bot

Loading