Repository navigation
[button] The Button Component #2138
Description
Feature request
Summary
Love the project, keen on integrating it on my workflows. Thus, reaching out about adding a Button component to base-ui that is fully WAI-ARIA compliant.
Please give feedback on the requirements spec I provided, or, just close this issue if you're already in progress for pushing Buttons to the library.
References
The WAI-ARIA Authoring Practices Guide provides a detailed example of how to implement an accessible button: Button Pattern
Motivation
I am not 100% sure what would meet your design philosophy, but, the following requirements spec is based on my assumptions of what would be ideal.
Requirements for the Base UI Button
Based on the WAI-ARIA specifications, the Button component should have the following:
- Role: The button defaults to the role
button. - Accessible Label: The button's accessible name should be computed from its text content. If there is no visible text, it should be provided via
aria-labelledbyoraria-label. - Description: If a description is present, it should be referenced using
aria-describedbyset to the ID of the description element. - Disabled State: When the button's action is unavailable,
aria-disabledshould be set totrue. - Toggle Button State: For toggle buttons,
aria-pressedshould be used with valuestrue(on) orfalse(off). - Menu Button Property: For menu buttons,
aria-haspopupshould be set tomenuortrue. - Keyboard Interaction: The button should be activatable with the
SpaceorEnterkeys. The focus behavior should depend on the type of action the button performs. - Default behaviour: The button should have default behaviour (ie:
Enter,Esc) which can be flagged via a prop passed to the button ortype.
Activity
mj12albert commentedon Jun 20, 2025
@ChrisCates The library provides "specific" buttons like
Dialog.Trigger,Menu.Trigger,Toggleetc instead of a single button that has to encompass everythingDo you have a use-case for a button that isn't covered yet?
ChrisCates commentedon Jun 20, 2025
@mj12albert, generic buttons (ie: a button to save, download, delete) and form submission buttons are very close in functionality and how their WAI attributes behave.
These buttons are not triggers or toggles.
mj12albert commentedon Jun 20, 2025
For a generic (native)
<button>element, standard HTML attributes already cover everything (role,aria-labeletc), andaria-disabledisn't needed for a native button.We recommend you make your own simple generic
Buttoncomponent in your design system or app that wraps a plain<button>and forwards the props like we do in our docs: https://github.com/mui/base-ui/blob/master/docs/src/components/GhostButton.tsxWe have a
Formcomponent, but the features aren't very advanced ATM compared to form libraries. In various demos we're just using<button type="submit">, but it's possible we could add aForm.Submit(and maybeForm.Reset) part as well. Here do you need any features that a native submit button doesn't provide? @ChrisCatesChrisCates commentedon Jun 20, 2025
@mj12albert, if the aria attributes are all redundant (which I was unaware of), I think clarity in the documentation would be great.
Form.SubmitandForm.Resetare nice in terms of keeping JSX structure clean. Otherwise, appreciate the clarity, add a section in the documentation for buttons though![-]The Button Component[/-][+][button] The Button Component[/+]