@metadiv-studio/select

A modern, accessible, and customizable select component for React applications. Built with TypeScript and Tailwind CSS, this component provides a clean and intuitive dropdown selection experience with optional search functionality.

📦 Installation

npm i @metadiv-studio/select

🎯 Features

• Modern Design: Clean, minimal interface that fits seamlessly into any design system
• Search Functionality: Optional built-in search with case-insensitive filtering
• Customizable Styling: Extensive customization options through CSS classes
• Accessibility: Proper keyboard navigation and screen reader support
• TypeScript Support: Full type safety with comprehensive interfaces
• Dark Mode Ready: Built-in dark mode support with Tailwind CSS
• Performance Optimized: Efficient rendering even with hundreds of options
• Responsive: Works perfectly on all device sizes

🚀 Quick Start

import Select from '@metadiv-studio/select';

function MyComponent() {
  const [value, setValue] = useState('');
  
  const options = [
    { label: 'Option 1', value: '1' },
    { label: 'Option 2', value: '2' },
    { label: 'Option 3', value: '3' }
  ];

  return (
    <Select
      items={options}
      value={value}
      onChange={setValue}
      placeholder="Choose an option..."
    />
  );
}

📖 API Reference

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | items | SelectItem[] | ✅ | - | Array of selectable options | | value | string | ✅ | - | Currently selected value | | onChange | (value: string) => void | ✅ | - | Callback when selection changes | | placeholder | string | ❌ | '' | Placeholder text when no option is selected | | className | string | ❌ | '' | CSS classes for the main container | | selectorClassName | string | ❌ | '' | CSS classes for the selector button | | optionsClassName | string | ❌ | '' | CSS classes for individual options | | search | boolean | ❌ | false | Enable search functionality |

SelectItem Interface

interface SelectItem {
  label: React.ReactNode    // Display text for the option
  value: string             // Unique identifier for the option
  searchValue?: string      // Optional text for search filtering
}

💡 Usage Examples

Basic Select

import Select from '@metadiv-studio/select';

function BasicSelect() {
  const [selected, setSelected] = useState('');
  
  const fruits = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Grape', value: 'grape' }
  ];

  return (
    <Select
      items={fruits}
      value={selected}
      onChange={setSelected}
      placeholder="Choose a fruit..."
    />
  );
}

Select with Search

function SearchableSelect() {
  const [selected, setSelected] = useState('');
  
  const jobRoles = [
    { 
      label: 'React Developer', 
      value: 'react',
      searchValue: 'React Developer Frontend JavaScript'
    },
    { 
      label: 'Python Developer', 
      value: 'python',
      searchValue: 'Python Developer Backend Django Flask'
    },
    { 
      label: 'DevOps Engineer', 
      value: 'devops',
      searchValue: 'DevOps Engineer CI/CD Docker Kubernetes'
    }
  ];

  return (
    <Select
      items={jobRoles}
      value={selected}
      onChange={setSelected}
      placeholder="Search for a job role..."
      search={true}
    />
  );
}

Custom Styling

function CustomStyledSelect() {
  const [selected, setSelected] = useState('');
  
  const colors = [
    { label: 'Red', value: 'red' },
    { label: 'Green', value: 'green' },
    { label: 'Blue', value: 'blue' }
  ];

  return (
    <Select
      items={colors}
      value={selected}
      onChange={setSelected}
      className="border-2 border-blue-500 rounded-lg"
      selectorClassName="bg-blue-50 hover:bg-blue-100"
      optionsClassName="hover:bg-blue-50"
    />
  );
}

Large Dataset Handling

function LargeSelect() {
  const [selected, setSelected] = useState('');
  
  // Generate 100+ options
  const countries = Array.from({ length: 150 }, (_, i) => ({
    label: `Country ${i + 1}`,
    value: `country-${i + 1}`,
    searchValue: `Country ${i + 1}`
  }));

  return (
    <Select
      items={countries}
      value={selected}
      onChange={setSelected}
      placeholder="Choose from 150+ countries..."
      search={true}
    />
  );
}

🎨 Styling

The component uses Tailwind CSS classes and can be customized through the className, selectorClassName, and optionsClassName props. The default styling follows a clean, minimal design that works well in both light and dark modes.

Default Styling Classes

• Container: relative
• Selector Button: flex items-center justify-between w-full px-2 h-7 text-sm border dark:border-white/10 rounded-md bg-transparent focus:border-primary dark:focus:border-primary
• Options: w-full px-2 h-7 text-left text-sm text-txtc-lv3 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-md

🌙 Dark Mode

The component automatically supports dark mode when using Tailwind CSS with the dark: prefix. No additional configuration is required.

🔧 Dependencies

This package has the following peer dependencies:

• react ^18
• react-dom ^18

And includes these internal dependencies:

• @metadiv-studio/button ^0.11.1
• @metadiv-studio/input ^0.1.1
• @radix-ui/react-scroll-area ^1.2.10

📱 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the UNLICENSED license.

🔗 Related Packages

• @metadiv-studio/button - Button component library
• @metadiv-studio/input - Input component library