Select Component

The Select component provides a modern, accessible dropdown input with support for single or multiple selection, icons, enhanced keyboard navigation, smooth animations, and extensive customization options.

Overview

The Select component offers modern UX patterns with:

Keyboard navigation with Arrow keys, Home, End, Enter, and Escape
Smooth animations with Framer Motion
Multiple size variants (sm/md/lg)
Comprehensive accessibility (ARIA attributes, screen reader support)
Rich content support (icons, custom styling)
Controlled and uncontrolled modes
Extensive customization layers

Option Structure

Each option in the Select component follows a structured format. You can enhance options with icons, descriptions, and even attach custom click handlers for advanced behaviors.

1type SelectOption = {
2  label: string; // Display text
3  value: string; // Unique value
4  icon?: React.ReactNode; // Optional icon
5  description?: string; // Optional secondary text
6  onClick?: (option, event) => void; // Custom click handler
7};

onClick: Trigger custom logic when an option is clicked (e.g., navigation, analytics, actions).

Note: The onClick runs before selection logic.

Import Component From Library

javascript

1import { Select } from "@neuctra/ui";

Single Select Usage Code

Use a string value for standard single selection. The component supports both controlled and uncontrolled modes.

jsx

1import { useState } from 'react';
2import { Select } from '@neuctra/ui';
3
4function BasicExample() {
5  const [value, setValue] = useState('');
6
7  const options = [
8    { label: 'Option 1', value: '1' },
9    { label: 'Option 2', value: '2' },
10    { label: 'Option 3', value: '3' }
11  ];
12
13  return (
14    <Select
15      options={options}
16      value={value}
17      onValueChange={setValue}
18      placeholder="Choose an option"
19    />
20  );
21}

Multiple Select Usage Code

Add multiple when the value should be an array of selected option values.

jsx

1import { useState } from 'react';
2import { Select } from '@neuctra/ui';
3
4function MultipleSelectExample() {
5  const [values, setValues] = useState([]);
6
7  const options = [
8    { label: 'React', value: 'react' },
9    { label: 'Vue', value: 'vue' },
10    { label: 'Angular', value: 'angular' },
11    { label: 'Svelte', value: 'svelte' }
12  ];
13
14  return (
15    <Select
16      multiple
17      options={options}
18      value={values}
19      onValueChange={setValues}
20      placeholder="Select frameworks"
21    />
22  );
23}

Basic Usage

Start with a simple select dropdown. The component supports both controlled and uncontrolled modes.

Multi-Select Mode

Enable multiple selection by setting the multiple prop to true. The component handles arrays of values automatically.

Option Click Actions

You can attach custom click handlers to individual options for advanced behaviors like logging, navigation, or triggering modals.

Hide Selection Indicator

Disable the check icon for a cleaner or menu-like appearance.

Rich Content Support

Add icons to options for better visual hierarchy and user experience. Icons can be any React node, such as a Lucide icon or custom element.

Labels, Helper Text & Validation

Use label, helperText, required, error, and success for form-ready states.

Priority*

Choose the priority for this task.

Owner

Owner is required

Size Variants

Choose from three size variants: sm, md (default), and lg.

Props Table

All available props for the Select component.

Prop	Type	Default	Description
label	string	—	Label displayed above the select.
name	string	—	Name used for form handling.
value	string \| string[]	—	Controlled value of the select.
defaultValue	string \| string[]	—	Initial value for uncontrolled mode.
onValueChange	(value, name?) => void	—	Callback when selection changes.
options	SelectOption[]	[]	List of selectable options.
placeholder	string	"Select..."	Text shown when no value selected.
showDescription	boolean	false	Shows description text under each option.
showCheckIcon	boolean	true	Controls visibility of the check icon for selected options.
disabled	boolean	false	Disables interaction.
required	boolean	false	Marks field as required.
error	string \| boolean	—	Error state or message.
success	boolean	false	Applies success styling.
helperText	string	—	Helper or validation message.
multiple	boolean	false	Enables multi-select mode.
labelIcon	React.ElementType	—	Icon shown with label.
prefixIcon	React.ElementType	—	Icon inside trigger (left side).
dropdownIcon	React.ElementType	ChevronDown	Icon for dropdown arrow.
searchable	boolean	false	Enables search input.
searchPlaceholder	string	"Search..."	Placeholder for search field.
searchClassName	string	—	Classes for the search input.
searchWrapperClassName	string	—	Classes for the wrapper around the search input, when searchable is set.
searchStyle	React.CSSProperties	—	Inline styles for the search input.
maxDropdownHeight	string \| number	"240px"	Maximum dropdown list height. Numbers are treated as pixels.
size	"sm" \| "md" \| "lg"	"md"	Controls trigger and item sizing.
className	string	—	Root container classes.
containerClassName	string	—	Additional classes for the root container.
labelClassName	string	—	Classes for the label element.
labelIconClassName	string	—	Classes for the label icon rendered before the label.
triggerClassName	string	—	Trigger button classes.
dropdownClassName	string	—	Dropdown container classes.
itemClassName	string	—	Option item classes.
itemLabelClassName	string	—	Classes for an option's label text.
itemDescriptionClassName	string	—	Classes for an option's description text, when showDescription is set.
emptyClassName	string	—	Classes for the "No options available" empty state.
iconClassName	string	—	Classes for prefix and dropdown icons.
helperClassName	string	—	Classes for helper or error text.
valueClassName	string	—	Selected value text styling.
itemIconClassName	string	—	Classes for option icons.
itemIconStyle	React.CSSProperties	—	Inline styles for option icons.
checkIconClassName	string	—	Classes for the selected check icon.
checkIconStyle	React.CSSProperties	—	Inline styles for the selected check icon.
style	React.CSSProperties	—	Inline styles for container.
triggerStyle	React.CSSProperties	—	Inline styles for trigger.
dropdownStyle	React.CSSProperties	—	Inline styles for dropdown.
itemStyle	React.CSSProperties	—	Inline styles for items.

Common Mistakes

<Select value={123} />

Value must be string or string[] — never number or object.

<Select options={[ "Apple", "Banana" ]} />

Options must be objects with label and value keys.

<Select value="a" defaultValue="b" />

Do not mix controlled (value) and uncontrolled (defaultValue).

<Select multiple value="single" />

When multiple is true, value must be an array of strings.

<Select options={[{label:"A", value:"a"}]} />

Always pass structured options with label and value.

options.filter(...).map(...) inside render

Large option lists without memoization can cause lag.

Pro Tips

Use controlled components for forms

Always use controlled Select components in forms for better validation and state management. This ensures form data is always in sync and validation works correctly.

tsx

1// ✅ Pro tip: Controlled form integration
2const [formData, setFormData] = useState({ category: '', priority: 'medium' });
3
4<Select
5  value={formData.category}
6  onValueChange={(value) => setFormData(prev => ({ ...prev, category: value }))}
7  // Form validation and submission will work reliably
8/>

Leverage rich content options

Use icons, descriptions, and custom styling to make your selects more informative and visually appealing. This improves user experience and reduces cognitive load.

tsx

1// ✅ Pro tip: Rich content for better UX
2const userOptions = [
3  {
4    label: 'John Doe',
5    value: 'john',
6    icon: <User size={16} />,
7    description: 'Senior Developer'
8  },
9  {
10    label: 'Jane Smith',
11    value: 'jane',
12    icon: <User size={16} />,
13    description: 'Product Manager'
14  }
15];
16
17<Select
18  options={userOptions}
19  showDescription
20  // Users can quickly identify options with visual cues
21/>

Optimize performance with large datasets

For selects with many options, consider virtualization or search functionality. Use the built-in search feature or implement custom filtering for better performance.

tsx

1// Pro tip: Search for large option lists
2<Select
3  options={largeOptionArray} // 100+ options
4  searchable // Built-in search functionality
5  searchPlaceholder="Type to search..."
6  // Users can quickly find options without scrolling through everything
7/>

Use size variants strategically

Choose appropriate sizes based on context. Use 'sm' for compact spaces, 'lg' for important selections, and 'md' (default) for most cases.

tsx

1// Pro tip: Size variants for different contexts
2// Compact forms or filters
3<Select size="sm" options={filterOptions} />
4
5// Main form fields
6<Select size="md" options={mainOptions} />
7
8// Important selections or mobile
9<Select size="lg" options={importantOptions} />

Combine with other form components

Select works great with other Neuctra UI components. Use consistent theming and spacing for cohesive form designs.

tsx

1// Pro tip: Consistent form design
2import { Select, Input, Button } from '@neuctra/ui';
3
4<div className="space-y-4 max-w-md">
5  <Input label="Name" placeholder="Enter your name" />
6  <Select
7    label="Category"
8    options={categoryOptions}
9  />
10  <Button type="submit">Submit</Button>
11</div>

Handle loading and disabled states

Provide appropriate feedback during loading states and disable selects when actions are unavailable. This improves perceived performance and prevents user confusion.

tsx

1// Pro tip: Loading and disabled states
2const [loading, setLoading] = useState(true);
3const [options, setOptions] = useState([]);
4
5useEffect(() => {
6  fetchOptions().then(setOptions).finally(() => setLoading(false));
7}, []);
8
9<Select
10  options={options}
11  disabled={loading}
12  placeholder={loading ? "Loading options..." : "Select an option"}
13  // Users understand the current state
14/>

Frequently Asked Questions

How do I install and import the Select component?

Install the @neuctra/ui package, then import it with: import { Select } from "@neuctra/ui";

What variants and sizes does Select support?

Select supports sizes: sm, md, lg. Use the variant and size props to switch between them, or pass a className to layer on custom Tailwind CSS classes.

Is the Select component accessible?

Select is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.