Select Component

A powerful, accessible, and highly customizable select component with search, grouping, keyboard navigation, and multiple variants for modern Angular applications.

Overview

The Select component is built with Angular 20+ signals and provides a comprehensive dropdown solution with advanced features like real-time search, option grouping, keyboard navigation, and full accessibility support. It's designed to work seamlessly with Angular reactive forms and offers extensive customization options.

Features

• ✅ Fully Accessible - WCAG 2.1 compliant with complete keyboard navigation and screen reader support
• ✅ High Performance - Optimized with Angular signals and OnPush change detection
• ✅ Searchable - Real-time filtering with customizable search functionality
• ✅ Grouped Options - Organize options into logical categories
• ✅ Multiple Variants - Default, success, warning, and destructive styles
• ✅ Responsive Design - Works perfectly on all screen sizes
• ✅ Dark Mode Support - Seamless light and dark theme integration
• ✅ Form Integration - Full support for Angular reactive forms
• ✅ Keyboard Navigation - Complete keyboard support with Tab cycling
• ✅ Custom Styling - Extensive customization options
• ✅ Animations - Smooth transitions with Angular Animations

Installation

npx ngsui-cli add select

Basic Usage

import { Component, signal } from '@angular/core';
import { SelectComponent, SelectOption } from '@angular-superui/lib';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [SelectComponent],
  template: `
    <SelectComponent
      [options]="options()"
      placeholder="Choose an option..."
      (valueChange)="onValueChange($event)"
    />
  `
})
export class ExampleComponent {
  readonly options = signal<SelectOption[]>([
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'orange', label: 'Orange' }
  ]);

  onValueChange(value: string | null) {
    console.log('Selected:', value);
  }
}

Examples

Searchable Select

@Component({
  template: `
    <SelectComponent
      [options]="countryOptions()"
      placeholder="Search countries..."
      searchable="true"
      (valueChange)="onCountryChange($event)"
    />
  `
})
export class SearchableExample {
  readonly countryOptions = signal<SelectOption[]>([
    { value: 'us', label: 'United States' },
    { value: 'ca', label: 'Canada' },
    { value: 'uk', label: 'United Kingdom' },
    // ... more options
  ]);
}

Grouped Options

@Component({
  template: `
    <SelectComponent
      [options]="techOptions()"
      placeholder="Choose technology..."
      searchable="true"
      (valueChange)="onTechChange($event)"
    />
  `
})
export class GroupedExample {
  readonly techOptions = signal<SelectOption[]>([
    { value: 'js', label: 'JavaScript', group: 'Frontend' },
    { value: 'react', label: 'React', group: 'Frontend' },
    { value: 'node', label: 'Node.js', group: 'Backend' },
    { value: 'python', label: 'Python', group: 'Backend' },
    { value: 'mysql', label: 'MySQL', group: 'Database' },
    // ... more options
  ]);
}

Options with Descriptions

@Component({
  template: `
    <SelectComponent
      [options]="planOptions()"
      placeholder="Choose your plan..."
      size="lg"
      (valueChange)="onPlanChange($event)"
    />
  `
})
export class PlanExample {
  readonly planOptions = signal<SelectOption[]>([
    {
      value: 'free',
      label: 'Free Plan',
      description: 'Perfect for getting started with basic features'
    },
    {
      value: 'pro',
      label: 'Pro Plan',
      description: 'Enhanced features for growing teams'
    },
    {
      value: 'enterprise',
      label: 'Enterprise Plan',
      description: 'Advanced features with dedicated support'
    }
  ]);
}

With Icons

@Component({
  template: `
    <SelectComponent
      [options]="statusOptions()"
      placeholder="Select status..."
      (valueChange)="onStatusChange($event)"
    />
  `
})
export class IconExample {
  readonly statusOptions = signal<SelectOption[]>([
    {
      value: 'active',
      label: 'Active',
      icon: '<svg class="w-4 h-4 text-green-500">...</svg>'
    },
    {
      value: 'pending',
      label: 'Pending',
      icon: '<svg class="w-4 h-4 text-yellow-500">...</svg>'
    },
    {
      value: 'inactive',
      label: 'Inactive',
      icon: '<svg class="w-4 h-4 text-gray-500">...</svg>'
    }
  ]);
}

Form Integration

import { Component } from '@angular/core';
import { FormBuilder, FormGroup, ReactiveFormsModule } from '@angular/forms';

@Component({
  selector: 'app-form-example',
  standalone: true,
  imports: [ReactiveFormsModule, SelectComponent],
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      <SelectComponent
        [options]="options()"
        placeholder="Choose an option..."
        formControlName="selectedOption"
      />
      <button type="submit">Submit</button>
    </form>
  `
})
export class FormExample {
  form: FormGroup;

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      selectedOption: ['']
    });
  }

  onSubmit() {
    console.log(this.form.value);
  }
}

Custom Styling

@Component({
  template: `
    <SelectComponent
      [options]="options()"
      placeholder="Custom styled select..."
      [customClasses]="{
        trigger: 'border-purple-300 focus:border-purple-500',
        content: 'border-purple-200',
        item: 'hover:bg-purple-50'
      }"
    />
  `
})
export class CustomStyledExample {
  // Component implementation
}

API Reference

SelectComponent

Inputs

Property	Type	Default	Description
options	SelectOption[]	[]	Required. Array of options to display
variant	'default' | 'destructive' | 'success' | 'warning'	'default'	Visual variant of the select
size	'xs' | 'sm' | 'default' | 'lg' | 'xl'	'default'	Size of the select component
disabled	boolean	false	Whether the select is disabled
placeholder	string	'Select an option...'	Placeholder text when no option is selected
searchable	boolean	false	Enable search functionality
selectId	string	'select'	Unique identifier for the select
allowClear	boolean	false	Show clear button when option is selected
clearText	string	'Clear selection'	Text for clear option
value	string | null	null	Currently selected value
customClasses	SelectCustomClasses	{}	Custom CSS classes for different parts
triggerClass	string	''	Deprecated. Custom CSS class for trigger
contentClass	string	''	Deprecated. Custom CSS class for content
ariaLabel	string	''	ARIA label for accessibility
srOnlyLabel	string	''	Screen reader only label
errorMessage	string	''	Error message for validation
helpText	string	''	Help text description
config	SelectConfig	{}	Advanced configuration options

Outputs

Event	Type	Description
valueChange	string | null	Emitted when selected value changes
optionSelect	SelectOption	Emitted when an option is selected
openChange	boolean	Emitted when dropdown open state changes
focus	void	Emitted when select receives focus
blur	void	Emitted when select loses focus
clear	void	Emitted when selection is cleared

Methods

Method	Parameters	Returns	Description
open()	-	void	Open the dropdown
close()	-	void	Close the dropdown
toggle()	-	void	Toggle dropdown open state
focusTrigger()	-	void	Focus the trigger element
blurTrigger()	-	void	Blur the trigger element

Interfaces

SelectOption

interface SelectOption {
  value: string;           // Unique value for the option
  label: string;           // Display text for the option
  disabled?: boolean;      // Whether option is disabled
  description?: string;    // Optional description text
  group?: string;          // Group name for grouping options
  icon?: string;           // HTML string for custom icon
}

SelectConfig

interface SelectConfig {
  allowClear?: boolean;          // Enable clear functionality
  placeholder?: string;          // Placeholder text
  searchPlaceholder?: string;    // Placeholder for search input
  noOptionsText?: string;        // Text when no options found
  clearText?: string;            // Text for clear option
  maxHeight?: string;            // Maximum height of dropdown
  placement?: 'bottom' | 'top' | 'auto';  // Dropdown placement
  customClasses?: SelectCustomClasses;    // Custom CSS classes
}

SelectCustomClasses

interface SelectCustomClasses {
  trigger?: string;      // CSS classes for trigger button
  content?: string;      // CSS classes for dropdown content
  item?: string;         // CSS classes for option items
  searchInput?: string;  // CSS classes for search input
}

Keyboard Navigation

The Select component provides comprehensive keyboard support:

Key	Action
Space / Enter	Open dropdown or select highlighted option
Arrow Down	Navigate to next option or open dropdown
Arrow Up	Navigate to previous option or open dropdown
Tab	Cycle through options when dropdown is open
Shift + Tab	Cycle through options in reverse
Escape	Close dropdown
Home	Navigate to first option
End	Navigate to last option
A-Z	Type to search (when searchable)

Accessibility

The Select component is built with accessibility as a priority:

• ARIA Support: Complete ARIA attributes including aria-expanded, aria-haspopup, aria-labelledby
• Keyboard Navigation: Full keyboard support for all interactions
• Screen Reader Support: Proper announcements and descriptions
• Focus Management: Logical focus flow and visual indicators
• High Contrast: Works with high contrast mode
• Reduced Motion: Respects user's motion preferences

Styling

CSS Custom Properties

You can customize the component using CSS custom properties:

.select-component {
  --select-border-radius: 0.375rem;
  --select-border-width: 1px;
  --select-transition-duration: 150ms;
  --select-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
}

Tailwind Classes

The component uses Tailwind CSS classes by default. You can override them using the customClasses input:

<SelectComponent
  [customClasses]="{
    trigger: 'border-2 border-blue-300 rounded-xl',
    content: 'shadow-2xl border-blue-200',
    item: 'py-3 px-4 hover:bg-blue-50'
  }"
/>

Performance Considerations

• OnPush Change Detection: The component uses OnPush strategy for optimal performance
• Signal-Based: Built with Angular signals for efficient reactivity
• Virtual Scrolling: For large datasets, consider implementing virtual scrolling
• Debounced Search: Search input is debounced to prevent excessive filtering

Best Practices

1. Option Limits: For better UX, consider pagination or virtualization for > 100 options
2. Search Thresholds: Enable search for lists with > 10 options
3. Grouping: Use groups to organize related options logically
4. Descriptions: Add descriptions for complex options to improve clarity
5. Loading States: Show loading indicators for async option loading
6. Error Handling: Provide clear error messages for validation failures

Common Patterns

Async Options Loading

@Component({
  template: `
    <SelectComponent
      [options]="options()"
      [disabled]="loading()"
      placeholder="Loading..."
      searchable="true"
    />
  `
})
export class AsyncExample {
  readonly loading = signal(false);
  readonly options = signal<SelectOption[]>([]);

  async loadOptions() {
    this.loading.set(true);
    try {
      const data = await this.apiService.getOptions();
      this.options.set(data);
    } finally {
      this.loading.set(false);
    }
  }
}

Dependent Selects

@Component({
  template: `
    <SelectComponent
      [options]="countries()"
      placeholder="Select country..."
      (valueChange)="onCountryChange($event)"
    />
    
    <SelectComponent
      [options]="cities()"
      [disabled]="!selectedCountry()"
      placeholder="Select city..."
    />
  `
})
export class DependentExample {
  readonly selectedCountry = signal<string | null>(null);
  readonly countries = signal<SelectOption[]>([]);
  readonly cities = signal<SelectOption[]>([]);

  onCountryChange(countryId: string | null) {
    this.selectedCountry.set(countryId);
    if (countryId) {
      this.loadCities(countryId);
    } else {
      this.cities.set([]);
    }
  }
}

Troubleshooting

Common Issues

1. Options not displaying: Ensure options array is properly structured
2. Form not updating: Check FormControl binding and change detection
3. Styling issues: Verify Tailwind CSS classes are available
4. Accessibility warnings: Check for proper ARIA labels and descriptions

Debug Mode

Enable debug mode to log component state:

// In development mode
if (!environment.production) {
  console.log('Select state:', selectComponent.selectService.isOpen());
}

Migration Guide

From v1 to v2

• triggerClass and contentClass are deprecated, use customClasses instead
• Signal-based API replaces observables for better performance
• New keyboard navigation behavior with Tab cycling

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Contributing

To contribute to the Select component:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

MIT License - see LICENSE file for details.