Star History

🚀 Features

📦 Installation

Prerequisites

1. Copy the Component

cp src/components/multi-select.tsx your-project/components/

2. Install Dependencies

npm install react react-domnpm install @radix-ui/react-popover @radix-ui/react-separatornpm install lucide-react class-variance-authority clsx tailwind-merge cmdk

3. Setup shadcn/ui Components

npx shadcn@latest add button badge popovercommand separator

4. Configure Path Aliases

For Next.js

{"compilerOptions": {"baseUrl":".","paths": {"@/*": ["./src/*"]}}}

For Vite

import{defineConfig}from"vite";importpathfrom"path";exportdefaultdefineConfig({resolve:{alias:{"@":path.resolve(__dirname,"./src"),},},});

For Webpack/Create React App

5. Setup Utility Function

import{typeClassValue,clsx}from"clsx";import{twMerge}from"tailwind-merge";exportfunctioncn(...inputs:ClassValue[]){returntwMerge(clsx(inputs));}

🎯 Quick Start

Basic Usage

import{MultiSelect}from"@/components/multi-select";import{useState}from"react";constoptions=[{value:"react",label:"React"},{value:"vue",label:"Vue.js"},{value:"angular",label:"Angular"},];functionApp(){const[selectedValues,setSelectedValues]=useState<string[]>([]);return(<MultiSelectoptions={options}onValueChange={setSelectedValues}defaultValue={selectedValues}/>);}

Custom Styling

conststyledOptions=[{value:"react",label:"React",icon:ReactIcon,style:{badgeColor:"#61DAFB",iconColor:"#282C34",},},{value:"vue",label:"Vue.js",icon:VueIcon,style:{gradient:"linear-gradient(135deg, #4FC08D 0%, #42B883 100%)",},},];<MultiSelectoptions={styledOptions}onValueChange={setSelected}placeholder="Select with custom styles..."/>;

Next.js Usage

"use client";import{MultiSelect}from"@/components/multi-select";import{useState}from"react";constoptions=[{value:"next",label:"Next.js"},{value:"react",label:"React"},{value:"typescript",label:"TypeScript"},];exportdefaultfunctionMyPage(){const[selected,setSelected]=useState<string[]>([]);return(<divclassName="container mx-auto p-4"><h1className="text-2xl font-bold mb-4">Select Technologies</h1><MultiSelectoptions={options}onValueChange={setSelected}placeholder="Select technologies..."variant="secondary"/></div>);}

Grouped Options

constgroupedOptions=[{heading:"Frontend Frameworks",options:[{value:"react",label:"React"},{value:"vue",label:"Vue.js"},{value:"angular",label:"Angular",disabled:true},],},{heading:"Backend Technologies",options:[{value:"node",label:"Node.js"},{value:"python",label:"Python"},],},];<MultiSelectoptions={groupedOptions}onValueChange={setSelected}placeholder="Select from groups..."/>;

📱 Responsive Design

Automatic Responsive Behavior

<MultiSelectoptions={options}onValueChange={setSelected}responsive={true}// Enable automatic responsive behaviorplaceholder="Responsive component"/>

Width Constraints

<MultiSelectoptions={options}onValueChange={setSelected}responsive={true}minWidth="200px"maxWidth="400px"placeholder="Constrained width"/>

📊 Dashboard Integration

Basic Dashboard Filtering

import{MultiSelect}from"@/components/multi-select";import{BarChart,Bar,XAxis,YAxis,ResponsiveContainer}from"recharts";constDashboard=()=>{const[selectedCategories,setSelectedCategories]=useState(["2024"]);constfilteredData=data.filter((item)=>selectedCategories.includes(item.category));return(<divclassName="space-y-4"><MultiSelectoptions={[{value:"2024",label:"2024",icon:CalendarIcon},{value:"2023",label:"2023",icon:CalendarIcon},]}onValueChange={setSelectedCategories}defaultValue={selectedCategories}placeholder="Select time period"responsive={true}/><ResponsiveContainerwidth="100%"height={300}><BarChartdata={filteredData}><XAxisdataKey="name"/><YAxis/><BardataKey="value"fill="#8884d8"/></BarChart></ResponsiveContainer></div>);};

Multi-level Filtering

constAdvancedDashboard=()=>{const[primaryFilters,setPrimaryFilters]=useState(["Performance"]);const[secondaryFilters,setSecondaryFilters]=useState(["Speed"]);return(<divclassName="space-y-4"><divclassName="grid grid-cols-2 gap-4"><MultiSelectoptions={primaryCategories}onValueChange={setPrimaryFilters}placeholder="Primary category"/><MultiSelectoptions={secondaryCategories}onValueChange={setSecondaryFilters}placeholder="Secondary filters"variant="secondary"/></div><ComposedChartdata={filteredData}>{/* Multiple chart types combined */}</ComposedChart></div>);};

📖 Examples

Basic Multi-Select

const[selectedValues,setSelectedValues]=useState<string[]>([]);<MultiSelectoptions={frameworks}onValueChange={setSelectedValues}defaultValue={selectedValues}placeholder="Select frameworks"/>;

With Icons and Custom Styling

const[selectedValues,setSelectedValues]=useState<string[]>([]);<MultiSelectoptions={frameworksWithIcons}onValueChange={setSelectedValues}defaultValue={selectedValues}placeholder="Select technologies"variant="inverted"maxCount={3}modalPopover={true}/>;

Async Data Loading

const[options,setOptions]=useState<Option[]>([]);const[loading,setLoading]=useState(true);useEffect(()=>{loadData().then((data)=>{setOptions(data);setLoading(false);});},[]);<MultiSelectoptions={options}onValueChange={setSelectedValues}defaultValue={selectedValues}placeholder={loading ?"Loading..." :"Select items"}disabled={loading}/>;

📚 API Reference

🎯 Best Practices

�📚 API Reference

Props

Types

AnimationConfig

interfaceAnimationConfig{badgeAnimation?:"bounce"|"pulse"|"wiggle"|"fade"|"slide"|"none";popoverAnimation?:"scale"|"slide"|"fade"|"flip"|"none";optionHoverAnimation?:"highlight"|"scale"|"glow"|"none";duration?:number;// Animation duration in secondsdelay?:number;// Animation delay in seconds}

MultiSelectRef

interfaceMultiSelectRef{reset:()=>void;// Reset to default valuegetSelectedValues:()=>string[];// Get current selectionsetSelectedValues:(values:string[])=>void;// Set selection programmaticallyclear:()=>void;// Clear all selectionsfocus:()=>void;// Focus the component}

MultiSelectOption

interfaceMultiSelectOption{label:string;// Display textvalue:string;// Unique identifiericon?:React.ComponentType<{// Optional icon componentclassName?:string;}>;disabled?:boolean;// Whether option is disabledstyle?:{// Custom stylingbadgeColor?:string;// Custom badge background coloriconColor?:string;// Custom icon colorgradient?:string;// Gradient background (CSS gradient)};}

MultiSelectGroup

interfaceMultiSelectGroup{heading:string;// Group heading textoptions:MultiSelectOption[];// Options in this group}

♿ Accessibility

ARIA Support

Keyboard Navigation

Screen Reader Announcements

Example with Enhanced Accessibility

<MultiSelectoptions={options}onValueChange={setSelected}placeholder="Choose frameworks (accessible)"// Accessibility features are built-in and automaticsearchable={true}aria-label="Framework selection"/>

Manual Accessibility Testing

// The component provides imperative methods for testingconstmultiSelectRef=useRef<MultiSelectRef>(null);// Programmatic focus for testingmultiSelectRef.current?.focus();// Check current selectionconstcurrentValues=multiSelectRef.current?.getSelectedValues();

🎨 Styling Examples

Custom Colors

// Single color badge with custom icon color{value:"react",label:"React",style:{badgeColor:"#61DAFB",iconColor:"#282C34"}}// Gradient badge (icon will be white by default){value:"vue",label:"Vue.js",style:{gradient:"linear-gradient(135deg, #4FC08D 0%, #42B883 100%)"}}// Multiple gradients{value:"angular",label:"Angular",style:{gradient:"linear-gradient(45deg, #DD0031 0%, #C3002F 50%, #FF6B6B 100%)"}}

Brand Colors

constbrandColors={react:{badgeColor:"#61DAFB",iconColor:"#282C34"},vue:{gradient:"linear-gradient(135deg, #4FC08D 0%, #42B883 100%)"},angular:{badgeColor:"#DD0031",iconColor:"#ffffff"},svelte:{gradient:"linear-gradient(135deg, #FF3E00 0%, #FF8A00 100%)"},node:{badgeColor:"#339933",iconColor:"#ffffff"},};

Animation Examples

// Wiggle animation with custom timing<MultiSelectoptions={options}onValueChange={setSelected}animationConfig={{badgeAnimation:"wiggle",duration:0.5,}}/>// Pulse animation with delay<MultiSelectoptions={options}onValueChange={setSelected}animationConfig={{badgeAnimation:"pulse",popoverAnimation:"fade",duration:0.3,delay:0.1,}}/>// Scale animation for popover<MultiSelectoptions={options}onValueChange={setSelected}animationConfig={{badgeAnimation:"slide",popoverAnimation:"scale",duration:0.4,}}/>

🎯 Advanced Examples

Advanced Animations

<MultiSelectoptions={options}onValueChange={setSelected}animationConfig={{badgeAnimation:"wiggle",popoverAnimation:"scale",duration:0.3,delay:0.1,}}placeholder="Animated component"/>

Programmatic Control via Ref

import{useRef}from"react";importtype{MultiSelectRef}from"@/components/multi-select";functionControlledExample(){constmultiSelectRef=useRef<MultiSelectRef>(null);consthandleReset=()=>{multiSelectRef.current?.reset();};consthandleClear=()=>{multiSelectRef.current?.clear();};consthandleSelectAll=()=>{constallValues=options.map((option)=>option.value);multiSelectRef.current?.setSelectedValues(allValues);};consthandleFocus=()=>{multiSelectRef.current?.focus();};return(<divclassName="space-y-4"><MultiSelectref={multiSelectRef}options={options}onValueChange={setSelected}placeholder="Controlled component"/><divclassName="flex gap-2"><buttononClick={handleReset}>Reset</button><buttononClick={handleClear}>Clear</button><buttononClick={handleSelectAll}>Select All</button><buttononClick={handleFocus}>Focus</button></div></div>);}

Auto-close on Select

<MultiSelectoptions={options}onValueChange={setSelected}closeOnSelect={true}placeholder="Closes after each selection"/>

Duplicate Handling

constoptionsWithDuplicates=[{value:"react",label:"React"},{value:"react",label:"React Duplicate"},// Will be handled{value:"vue",label:"Vue.js"},];<MultiSelectoptions={optionsWithDuplicates}onValueChange={setSelected}deduplicateOptions={true}// Automatically removes duplicatesplaceholder="Handles duplicates"/>;

With Form Integration (React Hook Form)

import{useForm,Controller}from"react-hook-form";import{zodResolver}from"@hookform/resolvers/zod";import{z}from"zod";constformSchema=z.object({technologies:z.array(z.string()).min(1,"Select at least one technology"),});functionMyForm(){constform=useForm({resolver:zodResolver(formSchema),defaultValues:{technologies:[]},});return(<formonSubmit={form.handleSubmit(onSubmit)}><Controllercontrol={form.control}name="technologies"render={({ field})=>(<MultiSelectoptions={techOptions}onValueChange={field.onChange}defaultValue={field.value}placeholder="Select technologies..."/>)}/></form>);}

Programmatic Control

functionControlledExample(){const[selected,setSelected]=useState<string[]>([]);constselectRandom=()=>{constrandomItems=options.filter((item)=>!item.disabled).sort(()=>0.5-Math.random()).slice(0,3).map((item)=>item.value);setSelected(randomItems);};return(<div><MultiSelectoptions={options}onValueChange={setSelected}defaultValue={selected}/><buttononClick={selectRandom}>Random Selection</button><buttononClick={()=>setSelected([])}>Clear All</button></div>);}

Custom Empty State

<MultiSelectoptions={options}onValueChange={setSelected}searchable={true}emptyIndicator={<divclassName="flex flex-col items-center p-4"><SearchIconclassName="h-8 w-8 text-muted-foreground mb-2"/><pclassName="text-muted-foreground">No items found</p><pclassName="text-xs text-muted-foreground">Try a different search term</p></div>}/>

Complex Grouped Structure

constcomplexStructure=[{heading:"Frontend Frameworks",options:[{value:"react",label:"React",icon:ReactIcon,style:{badgeColor:"#61DAFB",iconColor:"#282C34"},},{value:"vue",label:"Vue.js",icon:VueIcon,style:{gradient:"linear-gradient(135deg, #4FC08D 0%, #42B883 100%)",},},{value:"angular",label:"Angular",icon:AngularIcon,disabled:true,style:{badgeColor:"#DD0031",iconColor:"#ffffff"},},],},{heading:"State Management",options:[{value:"redux",label:"Redux"},{value:"zustand",label:"Zustand"},{value:"recoil",label:"Recoil",disabled:true},],},];

🎯 Use Cases

🛠️ Customization

Style Customization

<MultiSelectclassName="my-custom-class"options={options}onValueChange={setSelected}/>

Custom Variants

constcustomVariants=cva("base-classes",{variants:{variant:{// ... existing variantspremium:"bg-gradient-to-r from-purple-500 to-pink-500 text-white",minimal:"bg-transparent border-dashed",},},});

Theme Integration

📝 TypeScript Support

// All types are exported for useimporttype{MultiSelectOption,MultiSelectGroup,MultiSelectProps,MultiSelectRef,AnimationConfig,}from"@/components/multi-select";// Type-safe option creationconstcreateOption=(value:string,label:string,options?:Partial<MultiSelectOption>):MultiSelectOption=>({value,label,...options,});// Type-safe event handlersconsthandleChange=(values:string[])=>{// values is automatically typed as string[]console.log("Selected:",values);};

🚀 Getting Started

Clone and Run

# Clone the repositorygit clone https://github.com/sersavan/shadcn-multi-select-component.git# Navigate to the projectcd shadcn-multi-select-component# Install dependenciesnpm install# Start the development servernpm run dev# Open your browser to http://localhost:3000

Project Structure

├── src/│   ├── app/│   │   ├── page.tsx           # Demo page with examples│   │   ├── layout.tsx         # Root layout│   │   └── globals.css        # Global styles│   ├── components/│   │   ├── multi-select.tsx   # Main component│   │   ├── icons.tsx          # Icon components│   │   └── ui/                # shadcn/ui components│   └── lib/│       └── utils.ts           # Utility functions├── components.json            # shadcn/ui config├── tailwind.config.ts         # Tailwind configuration└── package.json              # Dependencies and scripts

🤝 Contributing

📄 License

🙏 Acknowledgments

🚀 Live Demo