CommandMenu

CommandMenu defines how EnterUI handles a command dialog for navigation and quick actions, including default structure, accessible states, and token-driven styling.

#Default usage

"use client";

import {
  Button,
  CommandMenu,
  CommandMenuContent,
  CommandMenuEmpty,
  CommandMenuGroup,
  CommandMenuInput,
  CommandMenuItem,
  CommandMenuList,
  CommandMenuTrigger,
  DialogDescription,
  DialogTitle,
  Text,
  VisuallyHidden,
  VStack,
} from "@froggdesign/enter-ui-react";
import { useState } from "react";

const commands = ["Open dashboard", "View components", "Browse themes"];

export function CommandMenuExample() {
  const [open, setOpen] = useState(false);
  const [query, setQuery] = useState("");
  const [selected, setSelected] = useState("");
  const matches = commands.filter((command) =>
    command.toLowerCase().includes(query.toLowerCase()),
  );

  return (
    <VStack gap={8} align="start">
      <CommandMenu open={open} onOpenChange={setOpen}>
        <CommandMenuTrigger asChild>
          <Button variant="secondary">Open command menu</Button>
        </CommandMenuTrigger>
        <CommandMenuContent>
          <VisuallyHidden>
            <DialogTitle>Quick commands</DialogTitle>
            <DialogDescription>
              Find a command and press Enter to select it.
            </DialogDescription>
          </VisuallyHidden>
          <CommandMenuInput
            aria-label="Find a command"
            value={query}
            onChange={(event) => setQuery(event.currentTarget.value)}
          />
          <CommandMenuList aria-label="Available commands">
            {matches.length > 0 ? (
              <CommandMenuGroup heading="Navigation">
                {matches.map((command) => (
                  <CommandMenuItem
                    key={command}
                    onSelect={() => {
                      setSelected(command);
                      setOpen(false);
                    }}
                  >
                    {command}
                  </CommandMenuItem>
                ))}
              </CommandMenuGroup>
            ) : (
              <CommandMenuEmpty>No commands found.</CommandMenuEmpty>
            )}
          </CommandMenuList>
        </CommandMenuContent>
      </CommandMenu>
      <Text size="sm" tone="muted" role="status">
        {selected
          ? `Selected: ${selected}`
          : "Choose a command to see the result."}
      </Text>
    </VStack>
  );
}

#Import

import {
  Button,
  CommandMenu,
  CommandMenuContent,
  CommandMenuEmpty,
  CommandMenuGroup,
  CommandMenuInput,
  CommandMenuItem,
  CommandMenuList,
  CommandMenuTrigger,
  DialogDescription,
  DialogTitle,
  VisuallyHidden,
} from "@froggdesign/enter-ui-react";

#Patterns

#Accessibility

The content uses Radix Dialog focus management. Include DialogTitle and DialogDescription; wrap them in VisuallyHidden when the search field is the visible header. Give the search input and list meaningful accessible labels.

• Opening places focus in CommandMenuInput. It is a combobox linked to the listbox, with aria-activedescendant tracking the highlighted command.
• ArrowDown / ArrowUp wrap through enabled, visible commands. Home and End highlight the first and last command. The input keeps focus so users can continue typing. Keyboard highlights scroll into view.
• Enter activates the highlighted command once; IME composition does not activate it. Escape closes the dialog and restores trigger focus.
• Filtering is controlled by the consumer. Changing the input clears the highlight; removed or disabled commands cannot remain active. Empty results do not activate a command on Enter.
• When no input is rendered, the listbox receives focus and supports the same keyboard navigation. Items expose aria-selected; groups are named by their headings.
• Mouse clicks and completed touch taps activate commands. Touching an item to scroll does not activate it immediately. Disabled commands remain inert.

The popup fits narrow viewports. The command list has its own bounded scroll area, and mobile search text remains 16px to avoid focus zoom. The shared component owns icon spacing, highlighted states, and pointer cursors.

#API

• CommandMenu: Radix Dialog root props, including open, defaultOpen, and onOpenChange. Call setOpen(false) from an action to close after selection.
• CommandMenuContent: Dialog content props, including onOpenAutoFocus and onKeyDown. Calling preventDefault() preserves a consumer's custom handling.
• CommandMenuItem: onSelect?: () => void, disabled, hidden, and button props. Items supply their own selection semantics and keyboard position.
• CommandMenuInput: native search input props such as value, onChange, and aria-label. Filtering remains consumer-controlled; the component provides combobox semantics and keyboard navigation.
• CommandMenuList: div props including id and aria-label; the input automatically follows a custom list ID.
• CommandMenuGroup: heading?: ReactNode and div props.
• Close, portal, empty, group, and list primitives are exported.

#Styling

Every exported component accepts className when it renders an element. EnterUI styles use .eui-* classes and --eui-* variables mapped from FroggDesign theme tokens.

#Descriptive search results

CommandMenuItem accepts leadingIcon, description, and metadata so result hierarchy and spacing stay in the component. Pass href for a native link or combine href with as={Link} for a routing-aware link component. Disabled links are excluded from keyboard selection and do not navigate.

CommandMenuInput trailing hosts a close or supporting action. CommandMenuList autoSelect highlights the first enabled result after filtering; the default keeps selection unset until the user navigates. CommandMenuFooter provides navigation, Enter, and Escape hints, or accepts custom children. Scrolling remains inside the list so input and hints stay visible. Supporting metadata is hidden below 600px to keep result text readable.