@octavian-tocan/react-dropdown

A flexible, composable dropdown (select) component system for React with TypeScript support. Built with accessibility in mind and featuring smooth animations powered by Motion (the latest version of Framer Motion).

Features

- 🎯 Composable API - Mix and match components or use pre-made convenience components
- 🔍 Searchable - Built-in search/filter functionality
- ♿ Accessible - Proper ARIA attributes and keyboard navigation
- 🎨 Customizable - Support for icons, descriptions, sections, and custom styling
- 📱 Portal Support - Render dropdowns in portals to avoid overflow clipping
- 🎭 Type-Safe - Full TypeScript support with generics
- ⚡ Performant - Optimized with React hooks and memoization

Installation

``bash
npm install @octavian-tocan/react-dropdown


or

pnpm add @octavian-tocan/react-dropdown

or

yarn add @octavian-tocan/react-dropdown
`

Peer Dependencies

This package requires:

- react >= 18
- react-dom >= 18
- motion >= 12 (Motion for React - the latest version of Framer Motion)

Quick Start

$3

`tsx
import Dropdown from '@octavian-tocan/react-dropdown';

function MyComponent() {
const [selectedLanguage, setSelectedLanguage] = useState(null);

const languages = [
{ code: 'en', name: 'English' },
{ code: 'es', name: 'Spanish' },
{ code: 'fr', name: 'French' },
];

return (
items={languages}
selectedItem={selectedLanguage}
onSelect={setSelectedLanguage}
getItemKey={(lang) => lang.code}
getItemDisplay={(lang) => lang.name}
>



);
}
`

$3

`tsx




`

$3

`tsx
import Dropdown from '@octavian-tocan/react-dropdown';
import { MoreHorizontal } from 'lucide-react';

function MenuExample() {
const menuItems = [
{ id: '1', label: 'Edit', icon: , onClick: handleEdit },
{ id: '2', label: 'Delete', icon: , onClick: handleDelete, showSeparator: true },
];

return (
items={menuItems}
trigger={}
onSelect={(item) => item.onClick()}
getItemKey={(item) => item.id}
getItemDisplay={(item) => item.label}
getItemIcon={(item) => item.icon}
getItemSeparator={(item) => item.showSeparator ?? false}
/>
);
}
`

API Reference

$3

The package exports a compound component Dropdown with the following sub-components:

- Dropdown.Root - Provider component that manages all state
- Dropdown.Trigger - Button that opens/closes the dropdown
- Dropdown.Content - Container for custom compositions
- Dropdown.Search - Search input component
- Dropdown.List - Scrollable list of options
- Dropdown.Simple - Pre-made dropdown with list only
- Dropdown.Searchable - Pre-made dropdown with search + list
- Dropdown.Menu - Action menu variant

$3

- useDropdownContext() - Access dropdown context (throws if used outside Root)
- useKeyboardNavigation(items, getItemKey, onSelect, closeDropdown) - Keyboard navigation helpers
- useClickOutside(ref, closeDropdown, isOpen) - Click outside detection

$3

All TypeScript types are exported. Key types include:

- DropdownRootProps
- DropdownTriggerProps
- DropdownListProps
- DropdownMenuProps
- DropdownContextValue
- DropdownSectionMeta
- DropdownPlacement

Advanced Usage

$3

Build your own dropdown layout:

`tsx






`

$3

Group items into sections with headers:

`tsx
items={items}
getItemSection={(item) => ({
key: item.category,
label: item.category,
icon: '📁',
})}
// ...
>
`

$3

Add icons and descriptions to items:

`tsx
items={items}
getItemIcon={(item) => }
getItemDescription={(item) => item.description}
// ...
>
`

$3

Render dropdown in a portal to avoid overflow clipping:

`tsx
items={items}
usePortal={true}
triggerRef={triggerRef}
// ...
>
`

$3

Control dropdown placement (top or bottom):

`tsx
items={items}
dropdownPlacement="top" // or "bottom" (default)
// ...
>
`

$3

Hide search input for small lists:

`tsx

`

When items.length <= hideSearchThreshold, search is hidden.

Examples

See the Storybook stories for comprehensive examples covering:

- Simple dropdowns
- Searchable dropdowns
- Action menus
- Custom compositions
- Sections and grouping
- Icons and descriptions
- Disabled items
- Portal rendering
- Placement options

Development

`bash


Install dependencies

pnpm install

Build

pnpm build

Type check

pnpm typecheck

Run tests

pnpm test

Watch mode

pnpm dev
``

License

MIT

Repository

https://github.com/OctavianTocan/react-dropdown