> Native Solid 2 fork. Original documentation and designs © WorkOS; historical posts retain their original context.
# Menu Bar
A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands.
## Features
- Can be controlled or uncontrolled.
- Supports submenus with configurable reading direction.
- Supports items, labels, groups of items.
- Supports checkable items (single or multiple).
- Customize side, alignment, offsets, collision handling.
- Optionally render a pointing arrow.
- Focus is fully managed.
- Full keyboard navigation.
- Typeahead support.
## Anatomy
Import all parts and piece them together.
```jsx
import { Menubar } from "@radix-solid/primitives";
export default () =>
;
```
## API Reference
### Root
Contains all the parts of a menubar.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `defaultValue`The value of the menu that should be open when initially rendered. Use when you do not need to control the value state. | `string` | — |
| `value`The controlled value of the menu to open. Should be used in conjunction with `onValueChange`. | `string` | — |
| `onValueChange`Event handler called when the value changes. | `function` | — |
| `dir`The reading direction. If omitted, inherits globally from `DirectionProvider` or assumes LTR (left-to-right) reading mode. | `enum` | — |
| `loop`When `true`, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | `false` |
### Menu
A top level menu item, contains a trigger with content combination.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `value`A unique value that associates the item with an active value when the navigation menu is controlled. This prop is managed automatically when uncontrolled. | `string` | — |
### Trigger
The button that toggles the content. By default, the `Menubar.Content` will position itself against the trigger.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| Data attribute | Values |
| -------------------- | ------------------------ |
| `[data-state]` | `"open" \| "closed"` |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### Portal
When used, portals the content part into the `body`.
| Prop | Type | Default |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------- |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. If used on this part, it will be inherited by `Menubar.Content` and `Menubar.SubContent` respectively. | `boolean` | — |
| `container`Specify a container element to portal the content into. | `HTMLElement` | `document.body` |
### Content
The component that pops out when a menu is open.
| Prop | Type | Default |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `loop`When `true`, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | `false` |
| `onCloseAutoFocus`Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onEscapeKeyDown`Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault` | `function` | — |
| `onPointerDownOutside`Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onFocusOutside`Event handler called when focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onInteractOutside`Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. It inherits from `Menubar.Portal`. | `boolean` | — |
| `side`The preferred side of the trigger to render against when open. Will be reversed when collisions occur and `avoidCollisions` is enabled. | `enum` | `"bottom"` |
| `sideOffset`The distance in pixels from the trigger. | `number` | `0` |
| `align`The preferred alignment against the trigger. May change when collisions occur. | `enum` | `"center"` |
| `alignOffset`An offset in pixels from the `"start"` or `"end"` alignment options. | `number` | `0` |
| `avoidCollisions`When `true`, overrides the `side` and`align` preferences to prevent collisions with boundary edges. | `boolean` | `true` |
| `collisionBoundary`The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Boundary` | `[]` |
| `collisionPadding`The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: `{ top: 20, left: 20 }`. | `number \| Padding` | `0` |
| `arrowPadding`The padding between the arrow and the edges of the content. If your content has `border-radius`, this will prevent it from overflowing the corners. | `number` | `0` |
| `sticky`The sticky behavior on the align axis. `"partial"` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `"always"` will keep the content in the boundary regardless. | `enum` | `"partial"` |
| `hideWhenDetached`Whether to hide the content when the trigger becomes fully occluded. | `boolean` | `false` |
| Data attribute | Values |
| -------------- | ---------------------------------------- |
| `[data-state]` | `"open" \| "closed"` |
| `[data-side]` | `"left" \| "right" \| "bottom" \| "top"` |
| `[data-align]` | `"start" \| "end" \| "center"` |
| CSS Variable | Description |
| ------------------------------------------ | ---------------------------------------------------------------------------- |
| `--radix-menubar-content-transform-origin` | The `transform-origin` computed from the content and arrow positions/offsets |
| `--radix-menubar-content-available-width` | The remaining width between the trigger and the boundary edge |
| `--radix-menubar-content-available-height` | The remaining height between the trigger and the boundary edge |
| `--radix-menubar-trigger-width` | The width of the trigger |
| `--radix-menubar-trigger-height` | The height of the trigger |
### Arrow
An optional arrow element to render alongside a menubar menu. This can be used to help visually link the trigger with the `Menubar.Content`. Must be rendered inside `Menubar.Content`.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `width`The width of the arrow in pixels. | `number` | `10` |
| `height`The height of the arrow in pixels. | `number` | `5` |
### Item
The component that contains the menubar items.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `onSelect`Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the menubar from closing when selecting that item. | `function` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | ------------------------ |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### Group
Used to group multiple `Menubar.Item`s.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
### Label
Used to render a label. It won't be focusable using arrow keys.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
### CheckboxItem
An item that can be controlled and rendered like a checkbox.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `checked`The controlled checked state of the item. Must be used in conjunction with `onCheckedChange`. | `boolean \| 'indeterminate'` | — |
| `onCheckedChange`Event handler called when the checked state changes. | `function` | — |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `onSelect`Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the menubar from closing when selecting that item. | `function` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | -------------------------- |
| `[data-state]` | `"checked" \| "unchecked"` |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### RadioGroup
Used to group multiple `Menubar.RadioItem`s.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `value`The value of the selected item in the group. | `string` | — |
| `onValueChange`Event handler called when the value changes. | `function` | — |
### RadioItem
An item that can be controlled and rendered like a radio.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `value*`The unique value of the item. | `string` | — |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `onSelect`Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the menubar from closing when selecting that item. | `function` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | -------------------------- |
| `[data-state]` | `"checked" \| "unchecked"` |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### ItemIndicator
Renders when the parent `Menubar.CheckboxItem` or `Menubar.RadioItem` is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. | `boolean` | — |
| Data attribute | Values |
| -------------- | -------------------------- |
| `[data-state]` | `"checked" \| "unchecked"` |
### Separator
Used to visually separate items in a menubar menu.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
### Sub
Contains all the parts of a submenu.
| Prop | Type | Default |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------- | ------- |
| `defaultOpen`The open state of the submenu when it is initially rendered. Use when you do not need to control its open state. | `boolean` | — |
| `open`The controlled open state of the submenu. Must be used in conjunction with `onOpenChange`. | `boolean` | — |
| `onOpenChange`Event handler called when the open state of the submenu changes. | `function` | — |
### SubTrigger
An item that opens a submenu. Must be rendered inside `Menubar.Sub`.
| Prop | Type | Default |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `disabled`When `true`, prevents the user from interacting with the item. | `boolean` | — |
| `textValue`Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside. | `string` | — |
| Data attribute | Values |
| -------------------- | ------------------------ |
| `[data-state]` | `"open" \| "closed"` |
| `[data-highlighted]` | Present when highlighted |
| `[data-disabled]` | Present when disabled |
### SubContent
The component that pops out when a submenu is open. Must be rendered inside `Menubar.Sub`.
| Prop | Type | Default |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- |
| `asChild`Render through a single-target factory, merging props and behavior with the chosen host. Read our [Composition](../guides/composition) guide for more details. | `boolean` | `false` |
| `loop`When `true`, keyboard navigation will loop from last item to first, and vice versa. | `boolean` | `false` |
| `onEscapeKeyDown`Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault` | `function` | — |
| `onPointerDownOutside`Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onFocusOutside`Event handler called when focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `onInteractOutside`Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`. | `function` | — |
| `forceMount`Used to force mounting when more control is needed. Useful when controlling animation with Solid-compatible animation libraries. It inherits from `Menubar.Portal`. | `boolean` | — |
| `sideOffset`The distance in pixels from the trigger. | `number` | `0` |
| `align`The direction the submenu appears from its anchor item. May change when collisions occur. | `enum` | `"start"` |
| `alignOffset`An offset in pixels from the `"start"` or `"end"` alignment options. | `number` | `0` |
| `avoidCollisions`When `true`, overrides the `side` and`align` preferences to prevent collisions with boundary edges. | `boolean` | `true` |
| `collisionBoundary`The element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. | `Boundary` | `[]` |
| `collisionPadding`The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: `{ top: 20, left: 20 }`. | `number \| Padding` | `0` |
| `arrowPadding`The padding between the arrow and the edges of the content. If your content has `border-radius`, this will prevent it from overflowing the corners. | `number` | `0` |
| `sticky`The sticky behavior on the align axis. `"partial"` will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst `"always"` will keep the content in the boundary regardless. | `enum` | `"partial"` |
| `hideWhenDetached`Whether to hide the content when the trigger becomes fully occluded. | `boolean` | `false` |
| Data attribute | Values |
| -------------------- | ---------------------------------------- |
| `[data-state]` | `"open" \| "closed"` |
| `[data-side]` | `"left" \| "right" \| "bottom" \| "top"` |
| `[data-align]` | `"start" \| "end" \| "center"` |
| `[data-orientation]` | `"vertical" \| "horizontal"` |
| CSS Variable | Description |
| ------------------------------------------ | ---------------------------------------------------------------------------- |
| `--radix-menubar-content-transform-origin` | The `transform-origin` computed from the content and arrow positions/offsets |
| `--radix-menubar-content-available-width` | The remaining width between the trigger and the boundary edge |
| `--radix-menubar-content-available-height` | The remaining height between the trigger and the boundary edge |
| `--radix-menubar-trigger-width` | The width of the trigger |
| `--radix-menubar-trigger-height` | The height of the trigger |
## Examples
### With submenus
You can create submenus by using `Menubar.Sub` in combination with its parts.
```jsx
…
…
…
Sub menu →
Sub menu item
Sub menu item
…
```
### With disabled items
You can add special styles to disabled items via the `data-disabled` attribute.
```jsx
// index.tsx
import { Menubar } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.MenubarItem[data-disabled] {
color: gainsboro;
}
```
### With separators
Use the `Separator` part to add a separator between items.
```jsx
…
…
…
…
```
### With labels
Use the `Label` part to help label a section.
```jsx
…
Label
…
…
…
```
### With checkbox items
Use the `CheckboxItem` part to add an item that can be checked.
```jsx
import { createSignal } from "solid-js";
import { CheckIcon } from "@radix-solid/icons";
import { Menubar } from "@radix-solid/primitives";
export default () => {
const [checked, setChecked] = createSignal(true);
return
…
…
…
Checkbox item
;
};
```
### With radio items
Use the `RadioGroup` and `RadioItem` parts to add an item that can be checked amongst others.
```jsx
import { createSignal } from "solid-js";
import { CheckIcon } from "@radix-solid/icons";
import { Menubar } from "@radix-solid/primitives";
export default () => {
const [color, setColor] = createSignal("blue");
return
…
Red
Blue
;
};
```
### With complex items
You can add extra decorative elements in the `Item` parts, such as images.
```jsx
import { Menubar } from "@radix-solid/primitives";
export default () =>
…
Adolfo Hess
Miyah Myles
;
```
### Constrain the content/sub-content size
You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport.
We expose several CSS custom properties such as `--radix-menubar-trigger-width` and `--radix-menubar-content-available-height` to support this. Use them to constrain the content dimensions.
```jsx
// index.tsx
import { Menubar } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.MenubarContent {
width: var(--radix-menubar-trigger-width);
max-height: var(--radix-menubar-content-available-height);
}
```
### Origin-aware animations
We expose a CSS custom property `--radix-menubar-content-transform-origin`. Use it to animate the content from its computed origin based on `side`, `sideOffset`, `align`, `alignOffset` and any collisions.
```jsx
// index.tsx
import { Menubar } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.MenubarContent {
transform-origin: var(--radix-menubar-content-transform-origin);
animation: scaleIn 0.5s ease-out;
}
@keyframes scaleIn {
from {
opacity: 0;
transform: scale(0);
}
to {
opacity: 1;
transform: scale(1);
}
}
```
### Collision-aware animations
We expose `data-side` and `data-align` attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations.
```jsx
// index.tsx
import { Menubar } from "@radix-solid/primitives";
import "./styles.css";
export default () =>
…
;
```
```css
/* styles.css */
.MenubarContent {
animation-duration: 0.6s;
animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.MenubarContent[data-side="top"] {
animation-name: slideUp;
}
.MenubarContent[data-side="bottom"] {
animation-name: slideDown;
}
@keyframes slideUp {
from {
opacity: 0;
transform: translateY(10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@keyframes slideDown {
from {
opacity: 0;
transform: translateY(-10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
```
## Accessibility
Adheres to the [Menu Button WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) and uses [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex) to manage focus movement among menu items.
### Keyboard Interactions
| Key | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Space` | When focus is on `Menubar.Trigger`, opens the menubar and focuses the first item. When focus is on an item, activates the focused item. |
| `Enter` | When focus is on `Menubar.Trigger`, opens the associated menu. When focus is on an item, activates the focused item. |
| `ArrowDown` | When focus is on `Menubar.Trigger`, opens the associated menu. When focus is on an item, moves focus to the next item. |
| `ArrowUp` | When focus is on an item, moves focus to the previous item. |
| `ArrowRight``ArrowLeft` | When focus is on a `Menubar.Trigger`, moves focus to the next or previous item. When focus is on a `Menubar.SubTrigger`, opens or closes the submenu depending on reading direction. When focus is within a `Menubar.Content`, opens the next menu in the menubar. |
| `Esc` | Closes the currently open menu and moves focus to its `Menubar.Trigger`. |