@solid-aria/menu
v0.2.0
Published
Primitives for building accessible menu component.
Downloads
5,023
Readme
@solid-aria/menu
Menu displays a list of actions or options that a user can choose.
createMenu
- Provides the behavior and accessibility implementation for a menu component.createMenuTrigger
- Provides the behavior and accessibility implementation for a menu trigger.
Installation
npm install @solid-aria/menu
# or
yarn add @solid-aria/menu
# or
pnpm add @solid-aria/menu
createMenu
Provides the behavior and accessibility implementation for a menu component.
Features
There is no native element to implement a menu in HTML that is widely supported. createMenu
helps achieve accessible menu components that can be styled as needed.
ℹ️ Note: createMenu
only handles the menu itself. For a dropdown menu, combine with createMenuTrigger
.
- Exposed to assistive technology as a
menu
withmenuitem
children using ARIA - Support for single, multiple, or no selection
- Support for disabled items
- Support for sections
- Complex item labeling support for accessibility
- Support for mouse, touch, and keyboard interactions
- Tab stop focus management
- Keyboard navigation support including arrow keys, home/end, page up/down
- Automatic scrolling support during keyboard navigation
- Typeahead to allow focusing items by typing text
How to use it
This example uses HTML <ul>
and <li>
elements to represent the menu with the first item disabled, and applies props from createMenu
and createMenuItem
.
import { ForItems, Item } from "@solid-aria/collection";
import { AriaMenuItemProps, AriaMenuProps, createMenu, createMenuItem } from "@solid-aria/menu";
import { ParentProps } from "solid-js";
function Menu(props: AriaMenuProps) {
let ref: HTMLUListElement | undefined;
// Get props for the menu element
const { MenuProvider, menuProps, state } = createMenu(props, () => ref);
return (
<MenuProvider>
<ul
{...menuProps}
ref={ref}
style={{
padding: 0,
"list-style": "none",
border: "1px solid gray",
"max-width": "250px"
}}
>
<ForItems in={state.collection()}>
{item => (
<MenuItem key={item().key} onAction={props.onAction}>
{item().children}
</MenuItem>
)}
</ForItems>
</ul>
</MenuProvider>
);
}
function MenuItem(props: ParentProps<AriaMenuItemProps>) {
let ref: HTMLLIElement | undefined;
// Get props for the menu item element
const { menuItemProps, isFocused, isDisabled } = createMenuItem(props, () => ref);
return (
<li
{...menuItemProps}
ref={ref}
style={{
background: isFocused() ? "gray" : "transparent",
color: isFocused() ? "white" : null,
padding: "2px 5px",
outline: "none",
cursor: isDisabled() ? "default" : "pointer"
}}
>
{props.children}
</li>
);
}
function App() {
return (
<Menu onAction={key => alert(key)} aria-label="Actions" disabledKeys={["one"]}>
<Item key="one">One</Item>
<Item key="two">Two</Item>
<Item key="three">Three</Item>
</Menu>
);
}
Menu sections
This example shows how a menu can support sections with separators and headings using props from createMenuSection
. This is accomplished using three extra elements: an <li>
to contain the heading <span>
element, and a <ul>
to contain the child items. This structure is necessary to ensure HTML semantics are correct.
import { ForItems, Item, Section } from "@solid-aria/collection";
import {
AriaMenuItemProps,
AriaMenuProps,
AriaMenuSectionProps,
createMenu,
createMenuItem,
createMenuSection
} from "@solid-aria/menu";
import { ParentProps, Show } from "solid-js";
function Menu(props: AriaMenuProps) {
let ref: HTMLUListElement | undefined;
// Get props for the menu element
const { MenuProvider, menuProps, state } = createMenu(props, () => ref);
return (
<MenuProvider>
<ul
{...menuProps}
ref={ref}
style={{
padding: 0,
"list-style": "none",
border: "1px solid gray",
"max-width": "250px"
}}
>
<ForItems in={state.collection()}>
{section => (
<MenuSection heading={section().title}>
<ForItems in={section().childNodes}>
{item => (
<MenuItem key={item().key} onAction={props.onAction}>
{item().children}
</MenuItem>
)}
</ForItems>
</MenuSection>
)}
</ForItems>
</ul>
</MenuProvider>
);
}
function MenuSection(props: ParentProps<AriaMenuSectionProps>) {
const { itemProps, headingProps, groupProps } = createMenuSection(props);
return (
<li {...itemProps}>
<Show when={props.heading}>
<span
{...headingProps}
style={{
"font-weight": "bold",
"font-size": "1.1em",
padding: "2px 5px"
}}
>
{props.heading}
</span>
</Show>
<ul
{...groupProps}
style={{
padding: 0,
"list-style": "none"
}}
>
{props.children}
</ul>
</li>
);
}
function MenuItem(props: ParentProps<AriaMenuItemProps>) {
let ref: HTMLLIElement | undefined;
// Get props for the menu item element
const { menuItemProps, isFocused, isDisabled } = createMenuItem(props, () => ref);
return (
<li
{...menuItemProps}
ref={ref}
style={{
background: isFocused() ? "gray" : "transparent",
color: isFocused() ? "white" : null,
padding: "2px 5px",
outline: "none",
cursor: isDisabled() ? "default" : "pointer"
}}
>
{props.children}
</li>
);
}
function App() {
return (
<Menu onAction={key => alert(key)} aria-label="Actions">
<Section key="section1" title="Section 1">
<Item key="section1-item1">One</Item>
<Item key="section1-item2">Two</Item>
<Item key="section1-item3">Three</Item>
</Section>
<Section key="section2" title="Section 2">
<Item key="section2-item1">One</Item>
<Item key="section2-item2">Two</Item>
<Item key="section2-item3">Three</Item>
</Section>
</Menu>
);
}
createMenuTrigger
Provides the behavior and accessibility implementation for a menu trigger.
Features
There is no native element to implement a menu in HTML that is widely supported. createMenuTrigger
combined with createMenu
helps achieve accessible menu components that can be styled as needed.
- Exposed to assistive technology as a button with a
menu
popup using ARIA (combined withcreateMenu
) - Support for mouse, touch, and keyboard interactions
- Keyboard support for opening the menu using the arrow keys, including automatically focusing the first or last item accordingly
How to use it
This example shows how to build a menu button using createMenuTrigger
, createButton
, and createMenu
.
The menu popup uses createMenu
and createMenuItem
to render the menu and its items. In addition, a <FocusScope>
is used to automatically restore focus to the trigger when the menu closes. A hidden <DismissButton>
is added at the start and end of the menu to allow screen reader users to dismiss it easily.
This example does not do any advanced popover positioning or portaling to escape its visual container.
import { createButton } from "@solid-aria/button";
import { ForItems, Item } from "@solid-aria/collection";
import { FocusScope } from "@solid-aria/focus";
import { createFocus } from "@solid-aria/interactions";
import {
AriaMenuItemProps,
AriaMenuProps,
AriaMenuTriggerProps,
createMenu,
createMenuItem,
createMenuTrigger
} from "@solid-aria/menu";
import { AriaOverlayProps, createOverlay, DismissButton } from "@solid-aria/overlays";
import { combineProps } from "@solid-primitives/props";
import { createSignal, FlowProps, JSX, ParentProps, Show } from "solid-js";
type MenuButtonProps = FlowProps<AriaMenuTriggerProps & AriaMenuProps & { label: JSX.Element }>;
function MenuButton(props: MenuButtonProps) {
let ref: HTMLButtonElement | undefined;
// Get props for the menu trigger and menu elements
const { menuTriggerProps, menuProps, state } = createMenuTrigger({}, () => ref);
// Get props for the button based on the trigger props from createMenuTrigger
const { buttonProps } = createButton(menuTriggerProps, () => ref);
return (
<div style={{ position: "relative", display: "inline-block" }}>
<button {...buttonProps} ref={ref} style={{ height: "30px", "font-size": "14px" }}>
{props.label}
<span aria-hidden="true" style={{ "padding-left": "5px" }}>
▼
</span>
</button>
<Show when={state.isOpen()}>
<MenuPopup
{...props}
{...menuProps}
autofocus={state.focusStrategy()}
onClose={() => state.close()}
/>
</Show>
</div>
);
}
function MenuPopup(props: AriaMenuProps & AriaOverlayProps) {
let ref: HTMLUListElement | undefined;
// Get props for the menu element
const { MenuProvider, menuProps, state } = createMenu(props, () => ref);
// Handle events that should cause the menu to close,
// e.g. blur, clicking outside, or pressing the escape key.
let overlayRef: HTMLDivElement | undefined;
const { overlayProps } = createOverlay(
{
onClose: props.onClose,
shouldCloseOnBlur: true,
isOpen: true,
isDismissable: true
},
() => overlayRef
);
// Wrap in <FocusScope> so that focus is restored back to the
// trigger when the menu is closed. In addition, add hidden
// <DismissButton> components at the start and end of the list
// to allow screen reader users to dismiss the popup easily.
return (
<MenuProvider>
<FocusScope restoreFocus>
<div {...overlayProps} ref={overlayRef}>
<DismissButton onDismiss={props.onClose} />
<ul
{...menuProps}
ref={ref}
style={{
position: "absolute",
width: "100%",
margin: "4px 0 0 0",
padding: 0,
"list-style": "none",
border: "1px solid gray",
background: "lightgray"
}}
>
<ForItems in={state.collection()}>
{item => (
<MenuItem key={item().key} onAction={props.onAction} onClose={props.onClose}>
{item().children}
</MenuItem>
)}
</ForItems>
</ul>
<DismissButton onDismiss={props.onClose} />
</div>
</FocusScope>
</MenuProvider>
);
}
function MenuItem(props: ParentProps<AriaMenuItemProps>) {
let ref: HTMLLIElement | undefined;
// Get props for the menu item element
const { menuItemProps } = createMenuItem(props, () => ref);
// Handle focus events so we can apply highlighted
// style to the focused menu item
const [isFocused, setIsFocused] = createSignal(false);
const { focusProps } = createFocus({ onFocusChange: setIsFocused });
const rootProps = combineProps(menuItemProps, focusProps);
return (
<li
{...rootProps}
ref={ref}
style={{
background: isFocused() ? "gray" : "transparent",
color: isFocused() ? "white" : "black",
padding: "2px 5px",
outline: "none",
cursor: "pointer"
}}
>
{props.children}
</li>
);
}
function App() {
return (
<MenuButton label="Actions" onAction={key => alert(key)}>
<Item key="copy">Copy</Item>
<Item key="cut">Cut</Item>
<Item key="paste">Paste</Item>
</MenuButton>
);
}
Internationalization
createMenu
handles some aspects of internationalization automatically. For example, type to select is implemented with an Intl.Collator
for internationalized string matching. You are responsible for localizing all menu item labels for content that is passed into the menu.
RTL
In right-to-left languages, the menu items should be mirrored. Ensure that your CSS accounts for this.
Changelog
All notable changes are described in the CHANGELOG.md file.