import { Menu } from "@bosunkit/components/menu";
import { Button } from "@bosunkit/components/button";
import { Stack } from "@bosunkit/components/stack";
import { useState, type Dispatch, type ReactElement, type SetStateAction } from "react";
export const description: string =
  "Compose a menu with a persistent option. Export previews the choice without downloading a file.";
export default function Showcase(): ReactElement {
  const [notes, setNotes]: [boolean, Dispatch<SetStateAction<boolean>>] = useState(true);
  const [status, setStatus]: [string, Dispatch<SetStateAction<string>>] = useState("");
  return (
    <Stack space="sm">
      <Menu.Root>
        <Menu.Trigger render={<Button>Report actions</Button>} />
        <Menu.Portal keepMounted>
          <Menu.Positioner sideOffset={8}>
            <Menu.Popup aria-label="Report actions">
              <Menu.Item
                onClick={(): void => {
                  setStatus(notes ? "Export preview includes notes." : "Export preview excludes notes.");
                }}
              >
                Preview export
              </Menu.Item>
              <Menu.CheckboxItem checked={notes} onCheckedChange={setNotes} closeOnClick={false}>
                Include notes<Menu.CheckboxItemIndicator> ✓</Menu.CheckboxItemIndicator>
              </Menu.CheckboxItem>
            </Menu.Popup>
          </Menu.Positioner>
        </Menu.Portal>
      </Menu.Root>
      <p role="status">{status}</p>
    </Stack>
  );
}

01Names describe behaviorUse the primitive for custom composition and a named recipe for an assembled control.

02One state contractControlled values, defaults and change callbacks follow Base UI; event details keep their reason and cancellation.

03Composition keeps semanticsA render target forwards its ref and every received DOM prop so keyboard interaction and accessible names survive.

Composition

Import { Menu } from @bosunkit/components/menu. Named parts follow Base UI Menu. Each part retains the upstream render, ref, DOM props, state attributes and event contracts. The kit supplies its typography, surfaces and scoped overlay presentation.

Examples

Custom composition

Compose a menu with a persistent option. Export previews the choice without downloading a file.

Code

import { Menu } from "@bosunkit/components/menu";
import { Button } from "@bosunkit/components/button";
import { Stack } from "@bosunkit/components/stack";
import { useState, type Dispatch, type ReactElement, type SetStateAction } from "react";
export const description: string =
  "Compose a menu with a persistent option. Export previews the choice without downloading a file.";
export default function Showcase(): ReactElement {
  const [notes, setNotes]: [boolean, Dispatch<SetStateAction<boolean>>] = useState(true);
  const [status, setStatus]: [string, Dispatch<SetStateAction<string>>] = useState("");
  return (
    <Stack space="sm">
      <Menu.Root>
        <Menu.Trigger render={<Button>Report actions</Button>} />
        <Menu.Portal keepMounted>
          <Menu.Positioner sideOffset={8}>
            <Menu.Popup aria-label="Report actions">
              <Menu.Item
                onClick={(): void => {
                  setStatus(notes ? "Export preview includes notes." : "Export preview excludes notes.");
                }}
              >
                Preview export
              </Menu.Item>
              <Menu.CheckboxItem checked={notes} onCheckedChange={setNotes} closeOnClick={false}>
                Include notes<Menu.CheckboxItemIndicator> ✓</Menu.CheckboxItemIndicator>
              </Menu.CheckboxItem>
            </Menu.Popup>
          </Menu.Positioner>
        </Menu.Portal>
      </Menu.Root>
      <p role="status">{status}</p>
    </Stack>
  );
}

Props

Prop	Type	Default	Description
motion	boolean \| undefined	–	Enable token-based transitions; false disables motion.
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.
children	React.ReactNode	–
id	string \| undefined	–
finalFocus	boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => boolean \| HTMLElement \| null \| void) \| undefined	–	Determines the element to focus when the menu is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.

Also takes every attribute of Primitive.Popup.Props.

Prop	Type	Default	Description
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.
nativeButton	boolean \| undefined	–	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
onClick	BaseUIComponentProps<'div', MenuItemState>['onClick'] \| undefined	–	The click handler for the menu item.
disabled	boolean \| undefined	–	Whether the component should ignore user interaction.
label	string \| undefined	–	Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided.
id	string \| undefined	–
closeOnClick	boolean \| undefined	–	Whether to close the menu when the item is clicked.

Also takes every attribute of Primitive.Item.Props.

Prop	Type	Default	Description
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.
nativeButton	boolean \| undefined	–	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
checked	boolean \| undefined	–	Whether the checkbox item is currently ticked. To render an uncontrolled checkbox item, use the `defaultChecked` prop instead.
defaultChecked	boolean \| undefined	–	Whether the checkbox item is initially ticked. To render a controlled checkbox item, use the `checked` prop instead.
onCheckedChange	((checked: boolean, eventDetails: MenuCheckboxItem.ChangeEventDetails) => void) \| undefined	–	Event handler called when the checkbox item is ticked or unticked.
onClick	BaseUIComponentProps<'div', MenuCheckboxItemState>['onClick'] \| undefined	–	The click handler for the menu item.
disabled	boolean \| undefined	–	Whether the component should ignore user interaction.
label	string \| undefined	–	Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided.
id	string \| undefined	–
closeOnClick	boolean \| undefined	–	Whether to close the menu when the item is clicked.

Also takes every attribute of Primitive.CheckboxItem.Props.

Prop	Type	Default	Description
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.
nativeButton	boolean \| undefined	–	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
valuerequired	any	–	Value of the radio item. This is the value that will be set in the MenuRadioGroup when the item is selected.
onClick	BaseUIComponentProps<'div', MenuRadioItemState>['onClick'] \| undefined	–	The click handler for the menu item.
disabled	boolean \| undefined	–	Whether the component should ignore user interaction.
label	string \| undefined	–	Overrides the text used for keyboard text navigation and filtering. Falls back to the rendered text when not provided.
id	string \| undefined	–
closeOnClick	boolean \| undefined	–	Whether to close the menu when the item is clicked.

Also takes every attribute of Primitive.RadioItem.Props.

Prop	Type	Default	Description
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.
anchor	Element \| null \| VirtualElement \| React.RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| undefined	–	An element to position the popup against. By default, the popup will be positioned against the trigger.
positionMethod	'absolute' \| 'fixed' \| undefined	–	Determines which CSS `position` property to use.
sideOffset	number \| OffsetFunction \| undefined	–	Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
alignOffset	number \| OffsetFunction \| undefined	–	Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
collisionBoundary	Boundary \| undefined	–	An element or a rectangle that delimits the area that the popup is confined to.
collisionPadding	Padding \| undefined	–	Additional space to maintain from the edge of the collision boundary.
sticky	boolean \| undefined	–	Whether to maintain the popup in the viewport after the anchor element was scrolled out of view.
arrowPadding	number \| undefined	–	Minimum distance to maintain between the arrow and the edges of the popup. Use it to prevent the arrow element from hanging out of the rounded corners of a popup.
disableAnchorTracking	boolean \| undefined	–	Whether to disable the popup from tracking any layout shift of its positioning anchor.
collisionAvoidance	CollisionAvoidance \| undefined	–	Determines how to handle collisions when positioning the popup. `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`): - `'flip'`: keep the requested side when it fits; otherwise try the opposite side (`top` and `bottom`, or `left` and `right`). - `'shift'`: never change side; keep the requested side and move the popup within the clipping boundary so it stays visible. - `'none'`: do not correct side-axis overflow. `align` controls overflow on the alignment axis (`start`/`center`/`end`): - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows. - `'shift'`: keep side and requested alignment, then nudge the popup along the alignment axis to fit. - `'none'`: do not correct alignment-axis overflow. `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the preferred axis cannot fit: - `'start'`: allow perpendicular fallback and try the logical start side first (`top` before `bottom`, or `left` before `right` in LTR). - `'end'`: allow perpendicular fallback and try the logical end side first (`bottom` before `top`, or `right` before `left` in LTR). - `'none'`: do not fallback to the perpendicular axis. When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`. If `align` is omitted, it defaults to `'flip'`.
align	UseAnchorPositioningSharedParameters['align'] \| undefined	–	How to align the popup relative to the specified side. Submenus and menubars default to `'start'`.
side	UseAnchorPositioningSharedParameters['side'] \| undefined	–	Which side of the anchor element to align the popup against. May automatically change to avoid collisions. Submenus and vertical menubars default to `'inline-end'`.

Also takes every attribute of Primitive.Positioner.Props.

Prop	Type	Default	Description
className	string \| ((state: State) => string \| undefined) \| undefined	–	CSS class applied to the element, or a function that returns a class based on the component's state.
render	React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> \| undefined	–	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
style	React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) \| undefined	–	Style applied to the element, or a function that returns a style object based on the component's state.

Also takes every attribute of Primitive.GroupLabel.Props.

Compose labeled parts and preserve their ref and DOM props.

Don't

Use the named parts for keyboard and focus behavior.

Do not replace semantic controls with clickable generic elements or discard event details.

Component API: naming, state, composition and compatibility.
Interaction states: focus, disabled and selected presentation.
Form field: the assembled label and validation recipe.

Composition

Examples

Custom composition

Props

Related