theReactSelect

A beautiful, fast, and accessible React Select component library built with TypeScript and Tailwind CSS. No external dependencies except React.

🌟 Live Demo

🚀 View Live Demo & Playground

Experience all features including:

• Interactive Playground - Test all configurations in real-time
• Live Examples - See components in action
• Complete Documentation - API reference and usage guides
• Dark/Light Mode - Toggle themes to see both modes
• Copy-Paste Code - Generated code for immediate use

Features

✨ Beautiful Design - Clean, modern interface with smooth animations
🚀 High Performance - Optimized for performance with minimal re-renders
♿ Fully Accessible - ARIA compliant with keyboard navigation
🎨 Highly Customizable - Multiple variants, sizes, and styling options
� Mobile Friendly - Touch-optimized for mobile devices
�🔍 Searchable - Built-in search functionality with debounced input
�️ Multi-select - Support for selecting multiple options with badges
🎯 TypeScript - Full TypeScript support with comprehensive types
🌙 Dark Mode - Built-in dark theme support
🧩 Zero Dependencies - Only peer dependencies on React
⚡ Select All - Bulk selection for multi-select mode
🎨 Badge Variants - Multiple badge styles for different use cases
� Flexible Display - Multiple ways to display selected items
🔢 Numbered Options - Optional numbering for better UX
👥 Grouped Options - Support for option grouping
🎛️ Custom Icons - Support for icons in options
📝 Rich Options - Options with descriptions and badges
🎪 Loading States - Built-in loading and error states
🧹 Clearable - Optional clear functionality
⌨️ Keyboard Navigation - Full keyboard support
🎭 Multiple Variants - Different visual styles to choose from

Installation

💡 Try it first: Check out the live demo and playground before installing!

# npm
npm install thereactselect

# pnpm  
pnpm add thereactselect

# yarn
yarn add thereactselect

# bun
bun add thereactselect

bun add thereactselect

Required CSS Variables

Add these CSS variables to your globals.css (Next.js) or index.css (React):

For Tailwind CSS v4 (Next.js)

@import 'tailwindcss';

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96%;
  --secondary-foreground: 222.2 84% 4.9%;
  --muted: 210 40% 96%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96%;
  --accent-foreground: 222.2 84% 4.9%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 221.2 83.2% 53.3%;
  --radius: 0.5rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;
  --popover: 222.2 84% 4.9%;
  --popover-foreground: 210 40% 98%;
  --primary: 217.2 91.2% 59.8%;
  --primary-foreground: 222.2 84% 4.9%;
  --secondary: 217.2 32.6% 17.5%;
  --secondary-foreground: 210 40% 98%;
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  --accent: 217.2 32.6% 17.5%;
  --accent-foreground: 210 40% 98%;
  --destructive: 0 62.8% 30.6%;
  --destructive-foreground: 210 40% 98%;
  --border: 217.2 32.6% 17.5%;
  --input: 217.2 32.6% 17.5%;
  --ring: 224.3 76.3% 94.1%;
}

For Traditional Tailwind CSS

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Add the same CSS variables as above */

Quick Start

import { Select } from 'thereactselect';

const options = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'orange', label: 'Orange' },
];

function App() {
  return (
    <Select
      options={options}
      placeholder="Select a fruit..."
      onValueChange={(value) => console.log(value)}
    />
  );
}

Examples

Basic Select

import React, { useState } from 'react';
import { Select } from 'thereactselect';

const options = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'orange', label: 'Orange' },
];

function BasicExample() {
  const [value, setValue] = useState();
  
  return (
    <Select
      options={options}
      value={value}
      onValueChange={setValue}
      placeholder="Select a fruit..."
    />
  );
}

Multi Select

function MultiSelectExample() {
  const [values, setValues] = useState([]);
  
  return (
    <Select
      options={options}
      multiple
      value={values}
      onValueChange={setValues}
      placeholder="Select multiple fruits..."
    />
  );
}

Multi Select with Select All

function SelectAllExample() {
  const [values, setValues] = useState([]);
  
  return (
    <Select
      options={options}
      multiple
      selectAll
      selectAllLabel="Select All Fruits"
      value={values}
      onValueChange={setValues}
      placeholder="Choose fruits..."
    />
  );
}

Searchable Select

function SearchableExample() {
  const [value, setValue] = useState();
  
  return (
    <Select
      options={options}
      searchable
      value={value}
      onValueChange={setValue}
      placeholder="Search fruits..."
      searchPlaceholder="Type to search..."
    />
  );
}

With Icons and Descriptions

import { Heart, Star, Award } from 'lucide-react';

const richOptions = [
  { 
    value: 'favorite', 
    label: 'Favorite', 
    icon: Heart,
    description: 'Your most loved option',
    badge: 'Popular',
    badgeVariant: 'success'
  },
  { 
    value: 'starred', 
    label: 'Starred', 
    icon: Star,
    description: 'Marked with a star',
    badge: 'New',
    badgeVariant: 'warning'
  },
  { 
    value: 'premium', 
    label: 'Premium', 
    icon: Award,
    description: 'Premium tier option',
    badge: 'Pro',
    badgeVariant: 'default'
  },
];

function RichOptionsExample() {
  const [value, setValue] = useState();
  
  return (
    <Select
      options={richOptions}
      value={value}
      onValueChange={setValue}
      placeholder="Select an option..."
    />
  );
}

Grouped Options

const groupedOptions = {
  groups: [
    {
      label: 'Fruits',
      options: [
        { value: 'apple', label: 'Apple' },
        { value: 'banana', label: 'Banana' },
      ]
    },
    {
      label: 'Vegetables',
      options: [
        { value: 'carrot', label: 'Carrot' },
        { value: 'lettuce', label: 'Lettuce' },
      ]
    }
  ]
};

function GroupedExample() {
  const [value, setValue] = useState();
  
  return (
    <Select
      {...groupedOptions}
      value={value}
      onValueChange={setValue}
      placeholder="Select food..."
    />
  );
}

Different Sizes and Variants

// Sizes
<Select options={options} size="sm" placeholder="Small" />
<Select options={options} size="default" placeholder="Default" />
<Select options={options} size="lg" placeholder="Large" />

// Variants
<Select options={options} variant="default" placeholder="Default variant" />
<Select options={options} variant="outline" placeholder="Outline variant" />

States and Loading

// Loading state
<Select options={options} loading placeholder="Loading..." />

// Error state
<Select options={options} error placeholder="Error state..." />

// Success state  
<Select options={options} success placeholder="Success state..." />

// Disabled
<Select options={options} disabled placeholder="Disabled..." />

Clearable and Custom Display

// Clearable
<Select 
  options={options} 
  clearable 
  value={value}
  onValueChange={setValue}
  placeholder="Clearable select..." 
/>

// Multi-select with different display modes
<Select 
  options={options}
  multiple
  selectedItemsDisplay="count"
  maxSelectedItemsToShow={2}
  value={values}
  onValueChange={setValues}
  placeholder="Display as count..."
/>

<Select 
  options={options}
  multiple
  selectedItemsDisplay="text"
  value={values}
  onValueChange={setValues}
  placeholder="Display as text..."
/>

Numbered Options

<Select 
  options={options}
  numbered
  value={value}
  onValueChange={setValue}
  placeholder="Numbered options..."
/>

// Custom number format
<Select 
  options={options}
  numbered
  numberFormat={(index) => `${index + 1})`}
  value={value}
  onValueChange={setValue}
  placeholder="Custom numbering..."
/>

Scrollable Dropdown with Custom Height

// Default scrollable dropdown (300px max height)
<Select 
  options={longListOfOptions}
  searchable
  placeholder="Select from many options..."
/>

// Custom max height
<Select 
  options={longListOfOptions}
  searchable
  scrollable
  maxHeight={500}
  placeholder="Taller dropdown..."
/>

// Disable scrolling (shows all options)
<Select 
  options={options}
  scrollable={false}
  placeholder="No scrolling..."
/>

API Reference

Types

SelectOption

interface SelectOption {
  value: string | number;
  label: string;
  disabled?: boolean;
  icon?: React.ComponentType<{ className?: string }>;
  description?: string;
  badge?: string;
  badgeVariant?: 'default' | 'secondary' | 'success' | 'warning' | 'error' | 'outline';
}

SelectGroup

interface SelectGroup {
  label: string;
  options: SelectOption[];
}

Main Component Props

Prop	Type	Default	Description
Basic Props
options	SelectOption[]	[]	Array of options to display
groups	SelectGroup[]	undefined	Grouped options (alternative to options)
value	string | number | (string | number)[]	undefined	Current selected value(s)
defaultValue	string | number | (string | number)[]	undefined	Default selected value(s)
placeholder	string	"Select..."	Placeholder text when no selection
onValueChange	(value: any) => void	undefined	Callback when selection changes
Selection Modes
multiple	boolean	false	Enable multi-select mode
selectAll	boolean	false	Show "Select All" option (multi-select only)
selectAllLabel	string	"Select All"	Label for select all option
Search & Filter
searchable	boolean	false	Enable search functionality
searchPlaceholder	string	"Search..."	Placeholder for search input
searchValue	string	undefined	Controlled search value
onSearchChange	(value: string) => void	undefined	Callback when search changes
Interaction
clearable	boolean	false	Show clear button when value selected
disabled	boolean	false	Disable the entire component
loading	boolean	false	Show loading spinner
closeOnSelect	boolean	true	Close dropdown after selecting an option
onOpenChange	(open: boolean) => void	undefined	Callback when dropdown opens/closes
Dropdown Behavior
scrollable	boolean	true	Enable scrolling when content exceeds maxHeight
maxHeight	number	300	Maximum height of dropdown in pixels
Styling & Variants
variant	"default" | "outline"	"default"	Visual style variant
size	"sm" | "default" | "lg"	"default"	Size variant
error	boolean	false	Show error state styling
success	boolean	false	Show success state styling
Multi-Select Display
selectedItemsDisplay	"badges" | "text" | "count"	"badges"	How to display selected items
maxSelectedItemsToShow	number	3	Max items before showing count
showItemClearButtons	boolean	true	Show X buttons on individual badges
Options Display
numbered	boolean	false	Show numbers next to options
numberFormat	(index: number) => string	undefined	Custom number formatting function
Groups Configuration
showGroupHeaders	boolean	true	Show group header labels
groupDividers	boolean	false	Show dividers between groups
Messages
noOptionsMessage	string	"No options available"	Message when no options
noSearchResultsMessage	string	"No results found"	Message when search yields no results
Styling Overrides
className	string	undefined	Additional CSS classes for container
triggerClassName	string	undefined	CSS classes for trigger button
dropdownClassName	string	undefined	CSS classes for dropdown
optionClassName	string	undefined	CSS classes for options
maxHeight	number	300	Maximum height of dropdown in pixels

Badge Variants

The badgeVariant prop on options supports these variants:

Variant	Description	Styling
default	Primary brand color	Blue theme colors
secondary	Muted appearance	Gray theme colors
success	Positive/success state	Green theme colors
warning	Warning/attention state	Yellow/orange theme colors
error	Error/danger state	Red theme colors
outline	Transparent with border	Border with theme colors

Selected Items Display Modes

When using multi-select, you can control how selected items are displayed:

Mode	Description
badges	Show individual badges for each selected item (default)
text	Show selected items as comma-separated text
count	Show count of selected items (e.g., "3 items selected")

Keyboard Navigation

Key	Action
Arrow Down	Move to next option
Arrow Up	Move to previous option
Enter	Select highlighted option
Space	Select highlighted option
Escape	Close dropdown
Tab	Move focus to next element

Accessibility Features

• ARIA Compliance: Full ARIA attributes for screen readers
• Keyboard Navigation: Complete keyboard support
• Focus Management: Proper focus handling and visual indicators
• Screen Reader Support: Descriptive labels and announcements
• High Contrast: Supports high contrast mode
• Role Attributes: Proper semantic roles for all elements

Styling and Theming

theReactSelect uses Tailwind CSS and CSS variables for theming. The component is fully themeable and supports dark mode out of the box.

CSS Variables Reference

The component uses these CSS variables for consistent theming:

:root {
  /* Layout Colors */
  --background: 0 0% 100%;              /* Main background */
  --foreground: 222.2 84% 4.9%;         /* Main text color */
  --card: 0 0% 100%;                    /* Card backgrounds */
  --card-foreground: 222.2 84% 4.9%;    /* Card text */
  --popover: 0 0% 100%;                 /* Popover background */
  --popover-foreground: 222.2 84% 4.9%; /* Popover text */
  
  /* Brand Colors */
  --primary: 221.2 83.2% 53.3%;         /* Primary brand color */
  --primary-foreground: 210 40% 98%;    /* Primary text */
  --secondary: 210 40% 96%;             /* Secondary backgrounds */
  --secondary-foreground: 222.2 84% 4.9%; /* Secondary text */
  
  /* UI Colors */
  --muted: 210 40% 96%;                 /* Muted backgrounds */
  --muted-foreground: 215.4 16.3% 46.9%; /* Muted text */
  --accent: 210 40% 96%;                /* Accent backgrounds */
  --accent-foreground: 222.2 84% 4.9%;  /* Accent text */
  --destructive: 0 84.2% 60.2%;         /* Error/danger color */
  --destructive-foreground: 210 40% 98%; /* Error text */
  
  /* Borders and Inputs */
  --border: 214.3 31.8% 91.4%;         /* Border color */
  --input: 214.3 31.8% 91.4%;          /* Input border */
  --ring: 221.2 83.2% 53.3%;           /* Focus ring */
  --radius: 0.5rem;                     /* Border radius */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;
  --popover: 222.2 84% 4.9%;
  --popover-foreground: 210 40% 98%;
  --primary: 217.2 91.2% 59.8%;
  --primary-foreground: 222.2 84% 4.9%;
  --secondary: 217.2 32.6% 17.5%;
  --secondary-foreground: 210 40% 98%;
  --muted: 217.2 32.6% 17.5%;
  --muted-foreground: 215 20.2% 65.1%;
  --accent: 217.2 32.6% 17.5%;
  --accent-foreground: 210 40% 98%;
  --destructive: 0 62.8% 30.6%;
  --destructive-foreground: 210 40% 98%;
  --border: 217.2 32.6% 17.5%;
  --input: 217.2 32.6% 17.5%;
  --ring: 224.3 76.3% 94.1%;
}

Custom Styling

You can customize the appearance using the provided className props:

<Select
  options={options}
  className="w-full max-w-md"           // Container styling
  triggerClassName="border-2"           // Trigger button styling  
  dropdownClassName="shadow-2xl"        // Dropdown styling
  optionClassName="hover:bg-blue-50"    // Individual option styling
/>

Responsive Design

The component is fully responsive and works well on all screen sizes:

<Select
  options={options}
  size="sm"                            // Smaller on mobile
  className="w-full sm:w-64 md:w-80"   // Responsive width
/>

Performance

theReactSelect is optimized for performance with several built-in optimizations:

• Debounced Search: Search input is debounced to prevent excessive filtering
• Minimal Re-renders: Optimized state management to minimize unnecessary renders
• Efficient Filtering: Fast client-side filtering with memoization
• Lightweight Bundle: Small bundle size with tree-shaking support
• Virtual Scrolling Ready: Can be extended with virtual scrolling for large datasets

Large Datasets

For very large datasets (1000+ options), consider:

// Use search to filter options
<Select
  options={largeDataset}
  searchable
  maxHeight={200}
  placeholder="Search from 1000+ options..."
/>

// Or limit initial options and load more
const [visibleOptions, setVisibleOptions] = useState(options.slice(0, 100));

Migration Guide

From react-select

theReactSelect provides a similar API to react-select with some differences:

// react-select
import Select from 'react-select';

<Select
  options={options}
  value={value}
  onChange={setValue}
  isMulti
  isSearchable
/>

// theReactSelect
import { Select } from 'thereactselect';

<Select
  options={options}
  value={value}
  onValueChange={setValue}
  multiple
  searchable
/>

Key Differences

Feature	react-select	theReactSelect
Multi-select	isMulti	multiple
Search	isSearchable	searchable
Change handler	onChange	onValueChange
Clear	isClearable	clearable
Loading	isLoading	loading
Disabled	isDisabled	disabled

Troubleshooting

Common Issues

Styling not appearing

Make sure you've included the required CSS variables in your global styles.

TypeScript errors

Ensure you're using the correct types:

import { Select, SelectOption } from 'thereactselect';

const options: SelectOption[] = [
  { value: 'apple', label: 'Apple' }
];

Search not working

Ensure the searchable prop is set to true:

<Select searchable options={options} />

Multi-select values not updating

Make sure you're using an array for multi-select values:

const [values, setValues] = useState<(string | number)[]>([]);

<Select
  multiple
  value={values}
  onValueChange={setValues}
  options={options}
/>

Browser Support

theReactSelect supports all modern browsers:

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

Accessibility

theReactSelect is built with accessibility as a core principle:

ARIA Support

• role="combobox" for the main trigger
• role="listbox" for the options container
• role="option" for individual options
• aria-expanded to indicate dropdown state
• aria-selected for selected options
• aria-disabled for disabled options
• aria-label and aria-labelledby support

Keyboard Navigation

Key	Action
Arrow Down	Move to next option
Arrow Up	Move to previous option
Enter	Select highlighted option
Space	Select highlighted option
Escape	Close dropdown
Tab	Move focus to next element
Home	Jump to first option
End	Jump to last option

Screen Reader Support

• Descriptive announcements for state changes
• Clear labeling of all interactive elements
• Proper focus management
• Selection announcements

Visual Accessibility

• High contrast mode support
• Clear focus indicators
• Sufficient color contrast ratios
• Scalable text and UI elements

Implementation Tips

// Always provide descriptive labels
<Select
  options={options}
  placeholder="Choose your preferred fruit"
  aria-label="Fruit selection"
/>

// Use proper labeling for forms
<label htmlFor="fruit-select">Favorite Fruit</label>
<Select
  id="fruit-select"
  options={options}
/>

Contributing

We welcome contributions! Please see our contributing guidelines:

Development Setup

# Clone the repository
git clone https://github.com/themrsami/thereactselect.git
cd thereactselect

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build:lib

# Run tests
npm test

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Update documentation if needed
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Code Style

• Use TypeScript for all new code
• Follow existing code formatting
• Add JSDoc comments for public APIs
• Include tests for new features
• Update documentation as needed

Reporting Issues

When reporting issues, please include:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Browser and version information
• Code examples if applicable

Links

• 🌐 Live Demo & Playground - Interactive examples and configuration
• 📦 NPM Package - Install and usage
• 📚 GitHub Repository - Source code and issues
• 🎮 Interactive Playground - Test all features
• 📖 Documentation - Complete API reference

License

MIT © Usama