theReactSelect

🌟 Live Demo

Features

Installation

# npm
npm install thereactselect
# pnpm 
pnpm add thereactselect
# yarn
yarn add thereactselect
# bun
bun add thereactselect

Required CSS Variables

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

Badge Variants

Selected Items Display Modes

Keyboard Navigation

Accessibility Features

Styling and Theming

CSS Variables Reference

: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

<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

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

Performance

Large Datasets

// 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

// 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

Troubleshooting

Common Issues

Styling not appearing

TypeScript errors

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

Search not working

<Select searchable options={options} />

Multi-select values not updating

const [values, setValues] = useState<(string | number)[]>([]);
<Select
 multiple
 value={values}
 onValueChange={setValues}
 options={options}
/>

Browser Support

Accessibility

ARIA Support

Keyboard Navigation

Screen Reader Support

Visual Accessibility

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

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

Code Style

Reporting Issues

Links

License