ComboBox Component

A powerful and accessible combobox component that combines an input field with a dropdown list. Features include real-time filtering, keyboard navigation, and customizable options. Perfect for searchable select inputs and autocomplete functionality.

Preview

Combo Box Component

Installation

npx shadcn@latest add combo-box.json

Basic Usage

After installation, import and use the ComboBox component in your React application:

API Reference

Props

| Prop | Type | Default | Description | | ------------- | ---------------------------------- | ----------------------- | --------------------------------------------------- | | options | string[] | [] | Array of options to display in the dropdown | | placeholder | string | "Select an option..." | Placeholder text for the input field | | onSelect | (option: string \| null) => void | undefined | Callback function called when an option is selected |

ComboBoxProps Interface

Features

🔍 Real-time Filtering

The component automatically filters options based on user input, providing instant search results.

🎯 Click Outside to Close

Dropdown automatically closes when clicking outside the component area.

🎨 Modern Design

Clean, modern interface with smooth transitions and hover effects.

📱 Responsive

Fully responsive design that works across all device sizes.

⌨️ Keyboard Accessible

Full keyboard navigation support with focus management.

Component Structure

The ComboBox component consists of several key elements:

1. Input Field

Text input with real-time filtering
Customizable placeholder text
Focus management and styling
Clear visual feedback

Chevron icon that rotates based on state
Click to toggle dropdown visibility
Smooth animation transitions

Filtered list of selectable options
Hover and focus states for better UX
Scrollable when content exceeds max height
"No options found" message when filter returns empty

4. State Management

Input value tracking
Dropdown open/close state
Selected option state
Filtered options based on input

Customization

Styling

The component uses Tailwind CSS classes. Customize the appearance by modifying the classes:

Custom Option Rendering

Extend the component to support custom option objects:

Color Themes

Customize colors to match your brand:

Advanced Examples

With Form Integration

Integrate with form libraries like React Hook Form:

Async Data Loading

Handle asynchronous option loading:

Multi-Select Variant

Extend for multi-select functionality:

Accessibility

The ComboBox component follows accessibility best practices:

ARIA Labels: Proper labeling for screen readers
Keyboard Navigation: Full keyboard support for all interactions
Focus Management: Clear focus indicators and logical tab order
Role Attributes: Semantic roles for better screen reader support
High Contrast: WCAG compliant color combinations

Keyboard Shortcuts

| Key | Action | | --------------- | ------------------------------ | | Tab | Navigate to/from the component | | Enter | Select highlighted option | | Escape | Close dropdown | | Arrow Up/Down | Navigate through options | | Type | Filter options in real-time |

Browser Support

The ComboBox component is compatible with all modern browsers:

✅ Chrome 70+
✅ Firefox 65+
✅ Safari 12+
✅ Edge 79+

Performance Considerations

Optimization Tips

Large Option Lists: Consider virtualization for 100+ options
Debounced Filtering: Add debouncing for API-based filtering
Memoization: Use React.memo for expensive option rendering
Lazy Loading: Load options on-demand when possible

Troubleshooting

Common Issues

Dropdown not closing on outside click

Ensure the component is properly mounted
Check for event listener conflicts

Options not filtering correctly

Verify the options prop is passed correctly
Check the filtering logic in useEffect

Styling issues

Ensure Tailwind CSS is properly configured
Check for CSS conflicts with existing styles

Performance issues with large lists

Consider implementing virtual scrolling
Add debouncing to the filter function
Use React.memo for option items