@versini/ui-dropdown

!npm package minimized gzipped size>)

> Accessible and flexible React dropdown menu components built with TypeScript, TailwindCSS, and Radix UI primitives.

The DropdownMenu package provides dropdown menus with full keyboard navigation, focus management, theming for triggers, and composable items / separators.

Table of Contents

- Features
- Installation
- Usage
- Examples
- API

Features

- 📋 Composable: DropdownMenu, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuGroupLabel, DropdownMenuSub
- 🔄 Nested Sub-menus: Support for multi-level menu hierarchies with automatic positioning
- ♿ Accessible: Built with Radix UI primitives & ARIA roles for robust a11y
- ⌨️ Keyboard Support: Arrow navigation, typeahead matching, ESC / click outside close
- 🎨 Theme & Focus Modes: Trigger inherits color + separate focus styling
- 🧭 Smart Positioning: Auto flip / shift to remain within viewport
- 🧪 Type Safe: Strongly typed props with TypeScript

Installation

``bash
npm install @versini/ui-dropdown
`

> Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

$3

`tsx
import { DropdownMenu, DropdownMenuItem } from "@versini/ui-dropdown";
import { ButtonIcon } from "@versini/ui-button";
import { IconMenu } from "@versini/ui-icons";

function App() {
return (
trigger={



}
>
label="Profile"
onSelect={() => console.info("Profile")}
/>
label="Settings"
onSelect={() => console.info("Settings")}
/>
label="Logout"
onSelect={() => console.info("Logout")}
/>

);
}
`

Examples

$3

`tsx
import {
DropdownMenu,
DropdownMenuItem,
DropdownMenuSeparator
} from "@versini/ui-dropdown";
import { ButtonIcon } from "@versini/ui-button";
import {
IconMenu,
IconUser,
IconSettings,
IconLogout
} from "@versini/ui-icons";

function AccountMenu() {
const [last, setLast] = useState("");
return (
label="Account options"
trigger={



}
onOpenChange={(o) => console.info("open?", o)}
>
label="Profile"
icon={}
onSelect={() => setLast("profile")}
/>
label="Settings"
icon={}
onSelect={() => setLast("settings")}
/>

label="Logout"
icon={}
onSelect={() => setLast("logout")}
/>

);
}
`

$3

`tsx
trigger={



}
>







`

$3

Create hierarchical menus using DropdownMenuSub:

`tsx
import {
DropdownMenu,
DropdownMenuItem,
DropdownMenuSub,
DropdownMenuGroupLabel
} from "@versini/ui-dropdown";
import { ButtonIcon } from "@versini/ui-button";
import { IconSettings, IconOpenAI, IconAnthropic } from "@versini/ui-icons";

function SettingsMenu() {
const [engine, setEngine] = useState("openai");

return (
trigger={



}
>



{/ Nested sub-menu with icon /}
}>
}>
Engines

label="OpenAI"
icon={}
selected={engine === "openai"}
onSelect={() => setEngine("openai")}
/>
label="Anthropic"
icon={}
selected={engine === "anthropic"}
onSelect={() => setEngine("anthropic")}
/>




);
}
`

Features of nested sub-menus:

- Automatically positioned to the right (or left if no space)
- Visual chevron indicator (→) shows expandable items
- Hover or click to open sub-menus
- Smart positioning adjusts for viewport constraints
- Keyboard navigation works across all levels
- Sibling sub-menus auto-close when opening another

API

$3

| Prop | Type | Default | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------- |
| trigger | React.ReactNode | - | Element used to open the menu (Button / ButtonIcon). |
| children | React.ReactNode | - | DropdownMenuItem, DropdownMenuSeparator, etc. |
| label | string | "Open menu" | Accessible label for the trigger. |
| defaultPlacement | "bottom" \| "bottom-start" \| "bottom-end" \| "top" \| "top-start" \| "top-end" \| "left" \| "left-start" \| "right" \| etc. | "bottom-start" | Initial preferred placement. |
| mode | "dark" \| "light" \| "system" \| "alt-system" | "system" | Color mode of trigger (when using UI buttons). |
| focusMode | "dark" \| "light" \| "system" \| "alt-system" | "system" | Focus ring thematic mode (when using UI buttons). |
| onOpenChange | (open: boolean) => void | - | Called when menu opens or closes. |
| sideOffset | number | 10 | Offset distance from the trigger element. |
| modal | boolean | true | Whether the dropdown is modal. |

$3

| Prop | Type | Default | Description |
| ------------- | ------------------------ | ----------- | --------------------------------------------- |
| label | string | - | The label to display for the menu item. |
| disabled | boolean | false | Whether the menu item is disabled. |
| icon | React.ReactNode | - | Icon to display on the left of the label. |
| raw | boolean | false | Disable internal styling for custom content. |
| ignoreClick | boolean | false | Prevent menu from closing when item selected. |
| selected | boolean | undefined | Show selected/unselected indicator. |
| onSelect | (event: Event) => void | - | Callback fired when the item is selected. |

$3

| Prop | Type | Default | Description |
| ------------- | ----------------- | ------- | ----------------------------------------- |
| label | string | - | The label for the sub-menu trigger. |
| icon | React.ReactNode | - | Icon to display on the left of the label. |
| children | React.ReactNode | - | Items to render inside sub-menu. |
| disabled | boolean | false | Whether the sub-menu is disabled. |
| sideOffset | number | 2 | Offset from sub-menu trigger. |
| alignOffset | number | -4 | Alignment offset for sub-menu. |

$3

Standard React.HTMLAttributes - use className for custom styling.

$3

| Prop | Type | Default | Description |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| icon | React.ReactNode | - | Icon to display on the left of the label. |
| children | React.ReactNode | - | The label content. |
| className | string` | - | Custom CSS class for styling. |