[toolbar] Toolbar element proposal

[lukewarlow]

A toolbar is a way to group related controls together and provide users quick access to commands. There is no dedicated <toolbar> element in HTML today; developers instead rely on generic containers like <div> with ARIA roles and JS to handle navigation. This proposal introduces a native <toolbar> element to give authors a semantic, accessible way to do this.

Toolbars are a common pattern across platforms. A standard element will make them easier to implement consistently on the web, while mapping directly to existing ARIA concepts. This helps assistive technology users understand relationships between grouped controls, and navigate between them more efficiently.

Use cases:

• The formatting toolbar in a document editor (bold, italic, underline, font family).
• The main command toolbar in a drawing or photo editing app.
• A simple toolbar with a search field and filter buttons in a catalogue.

Proposed design

At a high level, this proposal lets developers:

1. Use <toolbar> to group a set of interactive controls.
2. Expose accessible grouping and navigation consistent with ARIA toolbar behaviour.

See APG: https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/

[lukewarlow]

You can see a rough initial draft of an explainer at #1284

[css-meeting-bot]

The Open UI Community Group just discussed [toolbar] Toolbar element proposal, and agreed to the following:

• RESOLVED: Accept incubation of toolbar proposal. Needs lots of research of keyboard complexities and overflow.

The full IRC log of that discussion

<dbaron> Agenda: https://github.com/openui/open-ui/blob/main/meetings/telecon/2025-10-02.md
<jarhar> lwarlow: this came up in discussions about menu and menubar and some of the focusgroup discussions
<jarhar> lwarlow: it seems like it would be a good idea to get the ball rolling on a toolbar element
<jarhar> lwarlow: it might be quite a simple element
<jarhar> lwarlow: not much more to it than the work were doing for focusgroup and menubar
<jarhar> lwarlow: should be simpler than select, maybe not quite 5 years
<jarhar> lwarlow: ive done a pr for the initial explainer
<jarhar> lwarlow: by no means is it complete, but im hoping that its at a point that we can merge
<jarhar> lwarlow: its a new element, it has normal parsing behavior, its exposed as the aria toolbar role
<jarhar> lwarlow: doesnt have any special children, thats handled by existing html stuff such as buttons and other things
<masonf> <menuitem>?
<jarhar> lwarlow: potentially including the menulist stuff, common for toolbars to have menus
<jarhar> lwarlow: main behavior thing it provides is the arrow key navigation. it will have an implicit focusgroup with the toolbar behavior specified
<jarhar> lwarlow: theres many questions left to answer.
<masonf> q+
<jarhar> masonf: i like it. menuitems, would it be ok to put menuitems in there? is there a connection to the menu elements proposal that needs to be incorporated here?
<jarhar> lwarlow: you would have a button that opens a menulist as a potential item in here. you wouldnt use menuitems as i understand because those are only supposed to be in menulist/menubar roles
<jarhar> lwarlow: menubars are the thing you get at the top of macos for example
<jarhar> lwarlow: toolbars are more varied
<keithamus> q+
<jarhar> lwarlow: button with a menu dropdown. potentially a select. radio groups end up going in there quite a lot, or something along those lines. text adjustment, text alignment options. something like font selection would potentially be this, potentially be a menu
<jarhar> lwarlow: those would all be valid children. menuitems on their own dont seem correct, you should just use a button
<sarah6> q+
<masonf> ack mason
<masonf> ack keith
<jarhar> keithamus: one piece that is often very complex with toolbars is overflow. i think that seems like an omission that we should explore
<jarhar> keithamus: we want to make sure that developers are able to incorporate some sort of overflow into their menus
<jarhar> keithamus: if im doing overflow, then what does this give me? or if im doing overflow then this doesnt apply somehow
<jarhar> keithamus: we could do more there but thats going to be a very complex thing becaus overflow for buttons is simple enough because it becomes a menu, and the browser is good at handling layout so it can figure out which elements need to overflow
<jarhar> keithamus: it becomes a ux question when it comes to more complex things than buttons
<jarhar> keithamus: do you do nested menus? the firefox menu, the zoom buttons are a complex menu widget, its a group of buttons.
<flackr> overflow: popover / menu?
<jarhar> keithamus: some design systems try and issue that kind of behavior, if we are going to tackle overflow then things can overflow into rich widgets but they dont have to. it gets very complex
<keithamus> ack keithamus
<masonf> ack sarah
<jarhar> sarah6: +1 toolbar and overflow. we split it out from the toolbar because its used for other stuff, and its more complex than the toolbar itself
<jarhar> sarah6: this idea of putting lots of complex stuff like selects and radios, i guess its not that complex, but keyboard wise complex is useful but raises the question about keyboard behavior like arrow keys
<bkardell> +1 that is weird
<jarhar> sarah6: should they function differently? if you have radios in a toolbar, it should go through the radios and then go through the toolbar items. but if you have a select then you woudlnt want to go through every item in a select
<jarhar> sarah6: i imagine people are going to want to do that and its going to raise the question about how to handle the keyboard behavior there
<masonf> UX is too complicated. We should just go back to command line for everything.
<bkardell> Maybe if you do that, the universe should immediately end
<jarhar> lwarlow: yeah that second one is on my radar. im hoping it will get answered for free from focusgroup stuff
<jarhar> lwarlow: that will run into the same sort of issues
<jarhar> lwarlow: for hte raido button stuff it makes snse that if you have a horizontal toolbar it iwll go throug the radio items and then move on to the next item
<jarhar> lwarlow: whereas the select if youre going vertical, maybe you need a side key to open it, but that needs lots of thought
<jarhar> lwarlow: ill write those in a comment on the issue
<masonf> q?
<jarhar> lwarlow: does anyone oppose us incubating this idea?
<frehner> +1
<jarhar> keithamus: i think its a great start of things
<sarah6> +1 to not opposing :D
<bkardell> 🛳️
<bkardell> +1
<jarhar> masonf: you should resolve the comments you have on the explainer, but im in favor of landing the explainer and iterating in issues
<masonf> +1
<jarhar> +1
<lwarlow> Proposed Resolution: Accept incubation of toolbar proposal. Needs lots of research of keyboard complexities and overflow.
<sarah6> +1
<frehner> +1
<lwarlow> RESOLVED: Accept incubation of toolbar proposal. Needs lots of research of keyboard complexities and overflow.

[lukewarlow]

Points from meeting to look into:

• Need to look into how overflow handling is managed, apparently complicated. From @keithamus (@smhigley also agrees)
• Conflicting keyboard behaviours need thinking on (will be handled by focusgroup discussions in general even if that specific proposal doesn't proceed.)