@ngx-smart-forms/smart-selector

@ngx-smart-forms/smart-selector

Overview

@ngx-smart-forms/smart-selector is a comprehensive Angular library for building rich selection interfaces. It supports single and multi-selection, grid and list layouts, custom templates, and integrates seamlessly with Angular forms. The library is highly customizable with theming support, built-in validation, and event-driven workflows. Full accessibility (A11y) ensures your components are usable across all devices and assistive technologies.

Table of Contents

• Key Features
• Installation
• Live Demo
• Getting Started
• Usage
  • Single Selection
  • Multi-Selection
  • Grid Layout
  • Selection with Images
  • Max Selection Validation
  • Custom Templates
  • Custom Labels and Placeholders
  • Select All / Deselect All
• Properties
• Events
• Error Handling
• Theming and Styling
• Accessibility (A11y)
• Performance Considerations
• Best Practices and Edge Cases
• Support
• Contributing
• License

Key Features

• Single and Multi-Selection: Choose one or multiple items with ease.
• Grid and List Layouts: Adapt to any UI requirement.
• Custom Templates: Render options with images, icons, or advanced layouts.
• Validation Support: Manage selections with built-in Angular form validators.
• Event-Driven: Capture key events with dedicated callbacks.
• Theming: Use CSS variables for full styling control.
• Accessibility: Compliant with ARIA standards for keyboard and screen reader navigation.

Installation

npm install @ngx-smart-forms/smart-selector

Or:

yarn add @ngx-smart-forms/smart-selector

Live Demo

Check out a live interactive demo of the @ngx-smart-forms/smart-selector library on StackBlitz:

You can also click here to open the project in a new tab.

Getting Started

Importing and Using SmartSelector

import { Component } from '@angular/core';
import { FormBuilder, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { SmartSelector, SmartSelectorOption } from '@ngx-smart-forms/smart-selector';

@Component({
  selector: 'app-selector-demo',
  standalone: true,
  imports: [ReactiveFormsModule, SmartSelector],
  templateUrl: './selector-demo.component.html',
})
export class SelectorDemoComponent {
  form: FormGroup;
  options: SmartSelectorOption[] = [
    { id: '1', label: 'Strength' },
    { id: '2', label: 'Endurance' },
    { id: '3', label: 'Flexibility' },
    { id: '4', label: 'Cardio' },
    { id: '5', label: 'Power' },
  ];

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      selection: [null], // Single selection
      multiSelection: [[]], // Multi-selection
    });
  }

  onOptionChange(event: SmartSelectorOption | SmartSelectorOption[]) {
    console.log('Option changed:', event);
  }
}

Usage

1. Single Selection

<form [formGroup]="form">
  <smart-selector
    formControlName="selection"
    [options]="options"
    (optionChanged)="onOptionChange($event)"
  ></smart-selector>
</form>

2. Multi-Selection

<smart-selector
  formControlName="multiSelection"
  [options]="options"
  [multiSelect]="true"
  (optionChanged)="onOptionChange($event)"
></smart-selector>

3. Custom Grid Layout

<smart-selector
  [layout]="'grid'"
  [options]="options"
  (optionChanged)="onOptionChange($event)"
></smart-selector>

4. Selection with Images

<smart-selector
  [options]="imageOptions"
  [optionImage]="getImage"
  (optionChanged)="onOptionChange($event)"
></smart-selector>

  getImage(option: SmartSelectorOption): string | null {
    return option.image || null;
  }

5. Max Selection Validation

<smart-selector
  [multiSelect]="true"
  [maxSelection]="3"
  [options]="options"
  formControlName="multiSelection"
></smart-selector>
<div *ngIf="form.get('multiSelection')?.errors as errors">
  <div *ngIf="errors['maxSelection']">
    You can only select {{ errors['maxSelection'].maxAllowed }} options.
  </div>
</div>

6. Custom Template Rendering

<ng-template #customOption let-option let-selected="selected">
  <img [src]="option.image" alt="Option Image" />
  <p [class.selected]="selected">{{ option.label }}</p>
</ng-template>

<smart-selector
  [template]="customOption"
  [options]="options"
  [layout]="'grid'"
></smart-selector>

7. Custom Labels and Placeholders

<smart-selector
  [placeholder]="'Select an item'"
  [noOptionsText]="'No options available'"
  [ariaLabel]="'Custom Selector'"
  [options]="options"
></smart-selector>

8. Select All / Deselect All

<!-- Select All / Deselect All Checkbox -->
<label>
  <input type="checkbox" [smartToggleSelection]="selector" />
  Select/Deselect All
</label>

<!-- Smart Selector Component -->
<smart-selector
  #selector
  formControlName="multiSelection"
  [options]="options"
  [multiSelect]="true"
  (optionChanged)="onOptionChange($event)"
></smart-selector>

import { SmartSelector, SmartToggleSelection } from '@ngx-smart-forms/smart-selector';

@Component({
  selector: 'app-smart-selector-demo',
  standalone: true,
  imports: [
    SmartSelector,
    SmartToggleSelection,
  ],
  templateUrl: './smart-selector-demo.component.html',
  styleUrls: ['./smart-selector-demo.component.scss'],
})

Properties

Property	Type	Default	Description
options	SmartSelectorOption[]	[]	Array of selectable options.
multiSelect	boolean	false	Enable multi-selection mode.
layout	'list' | 'grid'	list	Layout type (list or grid).
maxSelection	number	Infinity	Maximum number of selections allowed.
placeholder	string	null	Placeholder text for empty selections.
noOptionsText	string	string	Message when no options are available.
ariaLabel	string	'Option'	Accessible label for screen readers.
optionLabel	(option) => string	string	Function to display custom labels.
optionImage	(option) => string | null	string	Function to display images for options.

Events

Event	Description
optionChanged	Triggered when an option is selected or deselected.
onSelect	Fired when an option is selected.
onDeselect	Fired when an option is deselected.
validationErrors	Emitted when validation errors occur.

Error Handling

• Max Selection Error: Triggers when the number of selected options exceeds the limit.
• FormControl Validation: Integrates with Angular forms for validation and error handling.

Theming and Styling

Customize the look and feel using the following CSS variables:

smart-selector {
  --selector-background-color: #f5f9fd;
  --selector-text-color: #333;
  --selector-active-background-color: #007bff;
  --selector-active-text-color: #fff;
  --selector-hover-background-color: #e9ecef;
  --selector-hover-text-color: #000;
  --selector-item-spacing: 10px;
  --selector-item-padding: 15px;
  --selector-item-border-radius: 4px;
  --grid-columns: repeat(auto-fit, minmax(150px, 1fr));
  --selector-disabled-background-color: #e0e0e0;
  --selector-disabled-text-color: #9e9e9e;
  --selector-disabled-cursor: not-allowed;
}

Accessibility (A11y)

• ARIA Attributes: Supports role="listbox" and aria-multiselectable attributes.
• Keyboard Navigation: Use arrow keys for option navigation.
• Screen Reader Support: Fully accessible with screen readers.

Performance Considerations

• OnPush Change Detection: Improves rendering performance.
• Lazy Rendering: Recommended for large datasets.
• Subscription Management: Unsubscribe from event subscriptions to prevent memory leaks.

Best Practices and Edge Cases

1. No Options Available: Use noOptionsText for better UX.
2. Grid Layout for Large Datasets: Enhances scrolling performance.
3. Handle Validation in Multi-Select Mode: Set maxSelection to avoid excessive selections.
4. Custom Templates: Use templates for advanced UI needs.

Support

If you encounter an issue, you can create a ticket

Contributing

We welcome contributions! Please see the CONTRIBUTING.md file for more information on how to get involved.

License

This library is licensed under the MIT License - see the LICENSE file for details.