# Svelte Perfect Select A modern, feature-rich, and fully accessible select component for **Svelte 5** applications. Built with react-select API compatibility, virtual scrolling, drag-drop, fuzzy search, and WCAG AAA accessibility. > **⚠️ v3.x requires Svelte 5!** If you're using Svelte 4, use v2.2.1 instead. ## ✨ What's New in v3.2.0 ### ☑️ **Group Selection** - Select or deselect entire groups with a single click - Works with multi-select mode and grouped options - Respects `maxSelected` limits and validation - Enable with `groupSelectsAll={true}` ### 👤 **Native Avatar Support** - No more custom templates for simple user lists! - Just add `image` or `avatar` to your option objects - Automatically renders circular avatars in options and tags - Controlled via `showAvatar={true}` ### 🏷️ **Floating Label Mode** - Material Design-style floating labels - Placeholder animates up when focused or has value - Use `floatingLabel={true}` to enable - Fully customizable via CSS ## ✨ What's New in v3.1.0 ### 🔍 **Search Highlighting** - Matched text is highlighted in yellow as you type - Configurable via `highlightSearchMatch` prop (default: `true`) - Custom CSS class via `highlightClassName` prop ### 📍 **Auto Dropdown Position** - Smart positioning based on available viewport space - Opens above input when insufficient space below - `menuPlacement="auto"` now properly calculates position ### 📝 **Enhanced Option Descriptions** - Show descriptions below option labels - Controlled via `showOptionDescriptions` prop (default: `true`) - Options with `description` property display subtitle text ## ✨ What's New in v3.0.0 ### 🚀 **Svelte 5 Migration** - Completely rewritten using Svelte 5 runes ($props, $state, $derived, $effect) - Event system migrated to callback props (onChange, onFocus, etc.) - Modern reactivity with fine-grained control ### ⚡ **Performance** - **Virtual Scrolling** - Handle 10,000+ options smoothly - Only renders visible items + overscan buffer - Automatic activation for 50+ options ### 🎯 **User Experience** - **Drag & Drop** - Reorder multi-select tags with visual feedback - **Command Palette Mode** - Cmd/Ctrl+K style interface - **Fuzzy Search** - Smart matching (e.g., "slct" matches "Select") - **Copy/Paste** - Multi-select clipboard support - **Custom Keyboard Shortcuts** - Define your own shortcuts ### 📱 **Mobile & Touch** - **Swipe-to-Remove** tags on mobile - Touch-optimized gestures - Mobile-first dropdown design ### ♿ **Accessibility** - **WCAG 2.1 AAA compliance** - ARIA live regions for screen readers - Real-time announcements for all actions - Enhanced focus management ### 🎨 **Advanced Features** - **Collapsible Groups** - Expand/collapse option groups - **Spring Animations** - Physics-based smooth motion - **Custom Templates** - Render Svelte components via snippets ## Features ### Core Features - **React-Select Compatible** - Full API compatibility with react-select - **Modern UI** - Beautiful design with smooth, enhanced animations - **Async Loading** - Load options asynchronously with caching support - **Creatable Options** - Allow users to create new options on the fly - **Search/Filter** - Built-in search functionality with custom filter support - **Multi-Select** - Support for selecting multiple options with animated tag chips - **Keyboard Navigation** - Full keyboard support (Arrow keys, Enter, Escape, Tab, Backspace) - **Accessibility** - ARIA labels and comprehensive screen reader support ### Advanced Features (v2.x) - **Select All / Deselect All** - One-click selection for multi-select mode - **Option Grouping** - Organize options into categories with sticky headers - **Icons in Options** - Add visual elements (SVG or images) to options - **Badges in Options** - Display status, roles, or categories with custom colors - **Color Themes** - 7 beautiful color themes: blue, purple, green, red, orange, pink, dark - **Container Sizing** - 5 physical container sizes: xs, sm, md, lg, xl - **Font Sizing** - 5 font size variants: smaller (11px), small (13px), medium (14px), large (16px), larger (18px) - **Custom Styles** - Inject custom styles for complete control over appearance - **Custom Render Functions** - `getOptionLabel`, `getOptionValue`, `isOptionDisabled` - **Flexible Options** - Support for option descriptions and disabled states - **Loading States** - Built-in loading indicators for sync and async operations - **RTL Support** - Right-to-left language support - **Menu Positioning** - Auto, top, or bottom placement with fixed positioning support - **Form Compatible** - Works seamlessly with native HTML forms - **Enhanced Animations** - Smooth dropdown animations, staggered options, and tag transitions - **Modern UI** - Beautiful design with enhanced shadows, backdrop blur effects, and rounded corners - **Max Selection Limit** - Limit the number of selections in multi-select mode - **Tag Overflow Display** - Show limited tags with "+X more" badge - **Validation States** - Built-in error, success, and warning states with messages - **Configurable Checkboxes** - Optional checkboxes for multi-select options - **Portal Rendering** - Render dropdown in a portal to solve z-index issues - **Infinite Scroll** - Load more options on scroll for large async datasets ### New in v3.2.0 - **Group Selection** - Select/deselect entire groups with checkbox in group header - **Native Avatar Support** - Display circular avatars from `image` or `avatar` fields - **Floating Label** - Material Design-style animated placeholder labels ### New in v3.1.0 - **Search Highlighting** - Matched text highlighted as you type - **Auto Dropdown Position** - Smart positioning based on viewport space - **Option Descriptions** - Show subtitle descriptions for options ### New in v3.0.0 - **Virtual Scrolling** - True virtualization for 10,000+ options - **Drag & Drop Reordering** - Reorder multi-select tags via drag-drop - **Command Palette Mode** - Cmd/Ctrl+K style centered modal interface - **Fuzzy Search** - Approximate matching algorithm - **Copy/Paste Support** - Clipboard integration for multi-select - **Custom Keyboard Shortcuts** - Define custom shortcut mappings - **Touch Optimizations** - Swipe gestures for mobile - **Collapsible Groups** - Click to expand/collapse option groups - **Spring Animations** - Physics-based motion with configurable stiffness/damping - **Custom Templates** - Render Svelte 5 snippets for options, tags, empty state - **WCAG 2.1 AAA** - Enhanced accessibility with live regions - **Enhanced Screen Reader** - Real-time announcements for all interactions ## Installation > **Requirements:** Svelte 5.0.0 or later Install using npm: ```bash npm i svelte-perfect-select ``` Install using yarn: ```bash yarn add svelte-perfect-select ``` Install using pnpm: ```bash pnpm add svelte-perfect-select ``` ## Basic Usage (Svelte 5) ```svelte ``` ### Group Selection (v3.2.0) ```svelte ``` ### Floating Label (v3.2.0) ```svelte

Selected: {selectedSkills.join(', ')}

``` ### Virtual Scrolling (v3.0.0) ```svelte ``` ### Command Palette Mode (v3.0.0) ```svelte ``` ### Custom Templates (v3.0.0) ```svelte ``` ### Collapsible Groups (v3.0.0) ```svelte console.log('Shortcut:', e.key)} placeholder="Try Ctrl+Shift+A..." /> ``` ### Search Highlighting (v3.1.0) ```svelte ``` ### Auto Dropdown Position (v3.1.0) ```svelte ``` ### Validation States ```svelte