MultiSelect Component

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-dom
npm install @radix-ui/react-popover @radix-ui/react-separator
npm install lucide-react class-variance-authority clsx tailwind-merge cmdk

3. Setup shadcn/ui Components

npx shadcn@latest add button badge popover command separator

4. Configure Path Aliases

For Next.js

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

For Vite

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

For Webpack/Create React App

5. Setup Utility Function

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
	return twMerge(clsx(inputs));
}

🎯 Quick Start

Basic Usage

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

Custom Styling

const styledOptions = [
	{
		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%)",
		},
	},
];
<MultiSelect
	options={styledOptions}
	onValueChange={setSelected}
	placeholder="Select with custom styles..."
/>;

Next.js Usage

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

Grouped Options

const groupedOptions = [
	{
		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" },
		],
	},
];
<MultiSelect
	options={groupedOptions}
	onValueChange={setSelected}
	placeholder="Select from groups..."
/>;

📱 Responsive Design

Automatic Responsive Behavior

<MultiSelect
	options={options}
	onValueChange={setSelected}
	responsive={true} // Enable automatic responsive behavior
	placeholder="Responsive component"
/>

Width Constraints

<MultiSelect
	options={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";
const Dashboard = () => {
	const [selectedCategories, setSelectedCategories] = useState(["2024"]);
	const filteredData = data.filter((item) =>
		selectedCategories.includes(item.category)
	);
	return (
		<div className="space-y-4">
			<MultiSelect
				options={[
					{ value: "2024", label: "2024", icon: CalendarIcon },
					{ value: "2023", label: "2023", icon: CalendarIcon },
				]}
				onValueChange={setSelectedCategories}
				defaultValue={selectedCategories}
				placeholder="Select time period"
				responsive={true}
			/>
			<ResponsiveContainer width="100%" height={300}>
				<BarChart data={filteredData}>
					<XAxis dataKey="name" />
					<YAxis />
					<Bar dataKey="value" fill="#8884d8" />
				</BarChart>
			</ResponsiveContainer>
		</div>
	);
};

Multi-level Filtering

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

📖 Examples

Basic Multi-Select

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

With Icons and Custom Styling

const [selectedValues, setSelectedValues] = useState<string[]>([]);
<MultiSelect
	options={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);
	});
}, []);
<MultiSelect
	options={options}
	onValueChange={setSelectedValues}
	defaultValue={selectedValues}
	placeholder={loading ? "Loading..." : "Select items"}
	disabled={loading}
/>;

📚 API Reference

🎯 Best Practices

�📚 API Reference

Props

Types

AnimationConfig

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

MultiSelectRef

interface MultiSelectRef {
	reset: () => void; // Reset to default value
	getSelectedValues: () => string[]; // Get current selection
	setSelectedValues: (values: string[]) => void; // Set selection programmatically
	clear: () => void; // Clear all selections
	focus: () => void; // Focus the component
}

MultiSelectOption

interface MultiSelectOption {
	label: string; // Display text
	value: string; // Unique identifier
	icon?: React.ComponentType<{
		// Optional icon component
		className?: string;
	}>;
	disabled?: boolean; // Whether option is disabled
	style?: {
		// Custom styling
		badgeColor?: string; // Custom badge background color
		iconColor?: string; // Custom icon color
		gradient?: string; // Gradient background (CSS gradient)
	};
}

MultiSelectGroup

interface MultiSelectGroup {
	heading: string; // Group heading text
	options: MultiSelectOption[]; // Options in this group
}

♿ Accessibility

ARIA Support

Keyboard Navigation

Screen Reader Announcements

Example with Enhanced Accessibility

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

Manual Accessibility Testing

// The component provides imperative methods for testing
const multiSelectRef = useRef<MultiSelectRef>(null);
// Programmatic focus for testing
multiSelectRef.current?.focus();
// Check current selection
const currentValues = 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

const brandColors = {
	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
<MultiSelect
 options={options}
 onValueChange={setSelected}
 animationConfig={{
 badgeAnimation: "wiggle",
 duration: 0.5,
 }}
/>
// Pulse animation with delay
<MultiSelect
 options={options}
 onValueChange={setSelected}
 animationConfig={{
 badgeAnimation: "pulse",
 popoverAnimation: "fade",
 duration: 0.3,
 delay: 0.1,
 }}
/>
// Scale animation for popover
<MultiSelect
 options={options}
 onValueChange={setSelected}
 animationConfig={{
 badgeAnimation: "slide",
 popoverAnimation: "scale",
 duration: 0.4,
 }}
/>

🎯 Advanced Examples

Advanced Animations

<MultiSelect
	options={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";
import type { MultiSelectRef } from "@/components/multi-select";
function ControlledExample() {
	const multiSelectRef = useRef<MultiSelectRef>(null);
	const handleReset = () => {
		multiSelectRef.current?.reset();
	};
	const handleClear = () => {
		multiSelectRef.current?.clear();
	};
	const handleSelectAll = () => {
		const allValues = options.map((option) => option.value);
		multiSelectRef.current?.setSelectedValues(allValues);
	};
	const handleFocus = () => {
		multiSelectRef.current?.focus();
	};
	return (
		<div className="space-y-4">
			<MultiSelect
				ref={multiSelectRef}
				options={options}
				onValueChange={setSelected}
				placeholder="Controlled component"
			/>
			<div className="flex gap-2">
				<button onClick={handleReset}>Reset</button>
				<button onClick={handleClear}>Clear</button>
				<button onClick={handleSelectAll}>Select All</button>
				<button onClick={handleFocus}>Focus</button>
			</div>
		</div>
	);
}

Auto-close on Select

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

Duplicate Handling

const optionsWithDuplicates = [
	{ value: "react", label: "React" },
	{ value: "react", label: "React Duplicate" }, // Will be handled
	{ value: "vue", label: "Vue.js" },
];
<MultiSelect
	options={optionsWithDuplicates}
	onValueChange={setSelected}
	deduplicateOptions={true} // Automatically removes duplicates
	placeholder="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";
const formSchema = z.object({
	technologies: z.array(z.string()).min(1, "Select at least one technology"),
});
function MyForm() {
	const form = useForm({
		resolver: zodResolver(formSchema),
		defaultValues: { technologies: [] },
	});
	return (
		<form onSubmit={form.handleSubmit(onSubmit)}>
			<Controller
				control={form.control}
				name="technologies"
				render={({ field }) => (
					<MultiSelect
						options={techOptions}
						onValueChange={field.onChange}
						defaultValue={field.value}
						placeholder="Select technologies..."
					/>
				)}
			/>
		</form>
	);
}

Programmatic Control

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

Custom Empty State

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

Complex Grouped Structure

const complexStructure = [
	{
		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

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

Custom Variants

const customVariants = cva("base-classes", {
	variants: {
		variant: {
			// ... existing variants
			premium: "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 use
import type {
	MultiSelectOption,
	MultiSelectGroup,
	MultiSelectProps,
	MultiSelectRef,
	AnimationConfig,
} from "@/components/multi-select";
// Type-safe option creation
const createOption = (
	value: string,
	label: string,
	options?: Partial<MultiSelectOption>
): MultiSelectOption => ({
	value,
	label,
	...options,
});
// Type-safe event handlers
const handleChange = (values: string[]) => {
	// values is automatically typed as string[]
	console.log("Selected:", values);
};

🚀 Getting Started

Clone and Run

# Clone the repository
git clone https://github.com/sersavan/shadcn-multi-select-component.git
# Navigate to the project
cd shadcn-multi-select-component
# Install dependencies
npm install
# Start the development server
npm 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