checkbox-selection-input

v15.0.5

Published

3 months ago

This is an Angular Module containing Components/Services using Material

Downloads

0High
0Medium
0Low

wavecoders

Checkbox Selection Input Component

Overview

The checkbox-selection-input library provides a comprehensive Material Design checkbox component that works seamlessly with Angular forms. It supports multiple selection with validation limits (min/max), disabled states, and both string and object data formats. The component implements Angular's ControlValueAccessor and NG_VALIDATORS interfaces for seamless form integration and validation.

Core Capabilities

☑️ Advanced Checkbox Selection Interface

Multiple Selection: Support for selecting multiple checkboxes simultaneously
Form Validation: Built-in min/max selection validation with error handling
Flexible Data Support: Accepts both string arrays and complex object arrays
State Management: Disabled states, pre-selected items, and dynamic enabling/disabling
Material Design: Built on Angular Material checkbox foundation
ControlValueAccessor Integration: Full Angular form control support
Validation Integration: Native Angular validation system compatibility
Dynamic Control: Runtime data updates and validation constraint changes

🔧 Features

✅ ControlValueAccessor Implementation - Works with Angular forms
✅ NG_VALIDATORS Integration - Native validation support
✅ Material Design Integration - Uses Angular Material components
✅ Multiple Selection - Select multiple items with checkboxes
✅ Min/Max Validation selection limits
✅ - Configurable Disable Max Behavior - Auto-disable checkboxes when max reached
✅ Flexible Data Types - Support strings and objects
✅ Pre-selection - Initialize with selected items
✅ Disabled Items - Mark individual items as non-selectable
✅ Change Detection - Console logging for debugging
✅ Form Integration - Reactive and template-driven forms

Key Benefits

| Feature | Description | |---------|-------------| | Flexible Selection | Support for multiple item selection with validation | | Rich Validation | Built-in min/max selection limits with error states | | Data Format Support | Works with simple strings or complex objects | | State Management | Disabled states and pre-selection capabilities | | Form Integration | Seamless Angular form control and validation integration | | Material Design | Consistent Material Design styling and behavior |

Demo Component (`CheckboxSelectionDemoComponent`)

The demo component showcases 6 different checkbox configurations demonstrating various use cases and validation scenarios.

Usage

To use the demo component in your application:

<app-checkbox-selection-demo></app-checkbox-selection-demo>

Demo Configurations

The demo includes 6 different checkbox setups:

Demo 1: Basic Configuration

No label/placeholder
Not required
Basic form control integration

Demo 2: Labeled Configuration

With label and placeholder
Required validation
Error display toggle

Demo 3: Minimum Selection

Label: "Providers"
Minimum 2 selections required
Error handling for insufficient selections

Demo 4: Maximum Selection

Label: "Providers"
Maximum 2 selections allowed
Error handling for exceeding limit

Demo 5: Auto-disable at Max

Label: "Providers"
Maximum 2 selections
Auto-disable remaining checkboxes when max reached

Demo 6: Combined Min/Max

Label: "Providers"
Minimum 1, Maximum 2 selections
Auto-disable at max
Complex validation scenarios

Demo Features

Data Type Toggle: Switch between string arrays and object arrays
Patch Testing: Programmatically set values for testing
Enable/Disable Controls: Test form control state changes
Change Detection: Console logging of value changes
Error Display: Toggle error message visibility
Reset Functionality: Clear all selections

Summary

The checkbox-selection-input library provides a flexible, Material Design-compliant checkbox component with comprehensive form integration, validation support, and multiple selection capabilities for Angular applications.

Quick Start Guide

Installation & Setup (2 minutes)

1. Import Module

// app.module.ts
import { CheckboxSelectionInputModule } from 'checkbox-selection-input';

@NgModule({
  imports: [
    CheckboxSelectionInputModule
  ]
})
export class AppModule { }

2. No Module Configuration Required

The CheckboxSelectionInputModule does not require global configuration. Components can be used immediately after module import.

Quick Examples

Example 1: Basic Multiple Selection

import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';

@Component({
  selector: 'app-basic-checkbox',
  template: `
    <app-checkbox-selection-input
      [formControl]="selectionControl"
      [data]="options">
    </app-checkbox-selection-input>
    
    <div>Selected: {{ selectionControl.value | json }}</div>
  `
})
export class BasicCheckboxComponent {
  selectionControl = new FormControl();
  
  options = ['Option 1', 'Option 2', 'Option 3', 'Option 4'];
}

Example 2: Required Selection with Validation

import { Component } from '@angular/core';
import { FormControl, Validators } from '@angular/forms';

@Component({
  selector: 'app-required-checkbox',
  template: `
    <app-checkbox-selection-input
      [formControl]="requiredControl"
      [data]="providers"
      label="Select Providers"
      placeholder="Choose your providers"
      [minSelection]="2"
      [maxSelection]="3">
    </app-checkbox-selection-input>
    
    <div class="errors" *ngIf="requiredControl.errors">
      <div *ngIf="requiredControl.hasError('minRequired')">
        Please select at least 2 providers
      </div>
      <div *ngIf="requiredControl.hasError('maxExceeded')">
        You can select maximum 3 providers
      </div>
      <div *ngIf="requiredControl.hasError('required')">
        Provider selection is required
      </div>
    </div>
  `
})
export class RequiredCheckboxComponent {
  requiredControl = new FormControl([], [
    Validators.required,
    Validators.minLength(2),
    Validators.maxLength(3)
  ]);
  
  providers = ['Telus', 'AT&T', 'Bell', 'Rogers', 'Verizon'];
}

Example 3: Object Data with Disabled Items

import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';
import { SelectionItem } from 'checkbox-selection-input';

@Component({
  selector: 'app-object-checkbox',
  template: `
    <app-checkbox-selection-input
      [formControl]="objectControl"
      [data]="userOptions"
      [disableMax]="true">
    </app-checkbox-selection-input>
    
    <div>Selected Users: {{ objectControl.value | json }}</div>
  `
})
export class ObjectCheckboxComponent {
  objectControl = new FormControl();
  
  userOptions = [
    { id: 1, value: 'John Doe', selected: true },
    { id: 2, value: 'Jane Smith', disabled: true },
    { id: 3, value: 'Bob Johnson', selected: true },
    { id: 4, value: 'Alice Brown' }
  ];
}

Example 4: Auto-disable at Maximum

import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';

@Component({
  selector: 'app-auto-disable-checkbox',
  template: `
    <app-checkbox-selection-input
      [formControl]="featuresControl"
      [data]="features"
      label="Select Features"
      [maxSelection]="2"
      [disableMax]="true">
    </app-checkbox-selection-input>
    
    <div class="info">
      Selected: {{ featuresControl.value?.length || 0 }} / 2 maximum
    </div>
  `
})
export class AutoDisableCheckboxComponent {
  featuresControl = new FormControl();
  
  features = [
    'Dark Mode',
    'Notifications',
    'Analytics',
    'Export Data',
    'API Access',
    'Advanced Filters'
  ];
}

Example 5: Dynamic Data with Form Validation

import { Component } from '@angular/core';
import { FormBuilder, Validators } from '@angular/forms';
import { SelectionItem } from 'checkbox-selection-input';

@Component({
  selector: 'app-dynamic-checkbox',
  template: `
    <form [formGroup]="dynamicForm">
      <app-checkbox-selection-input
        formControlName="permissions"
        [data]="permissionOptions"
        label="User Permissions"
        [minSelection]="1"
        [maxSelection]="4"
        [disableMax]="true">
      </app-checkbox-selection-input>
    </form>
    
    <div class="form-status">
      <div>Valid: {{ dynamicForm.get('permissions')?.valid }}</div>
      <div>Touched: {{ dynamicForm.get('permissions')?.touched }}</div>
      <div>Selected Count: {{ dynamicForm.get('permissions')?.value?.length || 0 }}</div>
    </div>
    
    <div class="controls">
      <button (click)="addPermission()">Add Permission</button>
      <button (click)="removeLastPermission()">Remove Last</button>
      <button (click)="resetForm()">Reset</button>
    </div>
  `,
  styles: [`
    .controls { margin-top: 1rem; display: flex; gap: 0.5rem; }
    .form-status { margin-top: 1rem; padding: 0.5rem; background: #f5f5f5; }
  `]
})
export class DynamicCheckboxComponent {
  constructor(private fb: FormBuilder) {}
  
  dynamicForm = this.fb.group({
    permissions: [[], [Validators.required, Validators.minLength(1), Validators.maxLength(4)]]
  });
  
  permissionOptions = [
    { id: 1, value: 'Read Files' },
    { id: 2, value: 'Write Files' },
    { id: 3, value: 'Delete Files' },
    { id: 4, value: 'Share Files' },
    { id: 5, value: 'Admin Access' }
  ];
  
  addPermission() {
    const availablePermissions = this.permissionOptions.filter(
      p => !this.dynamicForm.get('permissions')?.value?.includes(p.value)
    );
    if (availablePermissions.length > 0) {
      const current = this.dynamicForm.get('permissions')?.value || [];
      this.dynamicForm.get('permissions')?.setValue([...current, availablePermissions[0].value]);
    }
  }
  
  removeLastPermission() {
    const current = this.dynamicForm.get('permissions')?.value || [];
    if (current.length > 0) {
      this.dynamicForm.get('permissions')?.setValue(current.slice(0, -1));
    }
  }
  
  resetForm() {
    this.dynamicForm.get('permissions')?.reset();
  }
}

Component API

Inputs

Outputs

Form Control Integration

The component works with Angular form controls and emits:

Single array value: Array of selected values (strings or objects based on input data)
Validation state: Integrates with Angular's validation system
Touch/dirty states: Properly tracks form control states

Model Structures

SelectionItem Interface

export interface SelectionItemInterface {
  id: number | string;     // Unique identifier for the item
  value: string;           // The value to be selected/returned
  disabled?: boolean;      // Whether this item is disabled
  selected?: boolean;      // Whether this item is pre-selected
}

SelectionItem Class

export class SelectionItem implements SelectionItemInterface {
  constructor(
    public id = crypto.randomUUID(),  // Auto-generates UUID if not provided
    public value = '',
    public disabled?: boolean = false,
    public selected?: boolean = false,
  ) {}

  static adapt(item?: any): SelectionItem {
    return new SelectionItem(
      item?.id,                                    // Use provided ID or undefined
      (item?.value) ? item.value : item,           // Use value or fallback to item itself
      (item?.disabled) ? true : false,             // Convert to boolean
      (item?.selected) ? true : false,             // Convert to boolean
    );
  }
}

Usage Examples

// String array data (automatically converted to SelectionItem)
const stringData = ['Option 1', 'Option 2', 'Option 3'];

// Object array data
const objectData = [
  { id: 1, value: 'Telus', selected: true },
  { id: 2, value: 'AT&T', disabled: true },
  { id: 3, value: 'Bell' }
];

// Manual SelectionItem creation
const manualItems = [
  new SelectionItem('1', 'Option 1', false, true),
  new SelectionItem('2', 'Option 2', true, false),
  new SelectionItem('3', 'Option 3', false, false)
];

// Using adapt method for flexible data
const adaptedItems = [
  SelectionItem.adapt({ value: 'Item 1', selected: true }),
  SelectionItem.adapt({ id: 'custom-id', value: 'Item 2', disabled: true }),
  SelectionItem.adapt('Item 3') // String fallback
];

Form Integration

ControlValueAccessor Implementation

The component implements Angular's ControlValueAccessor interface:

// writeValue(value: string[]): void
// Sets the value of the control (array of selected values)
writeValue(value: string[]): void {
  // Handle incoming form control value
  // Update component state and checkbox states
}

// registerOnChange(fn: any): void
// Registers a callback for value changes
registerOnChange(fn: any): void {
  this.onChange = fn;
}

// registerOnTouched(fn: any): void
// Registers a callback for touch events
registerOnTouched(fn: any): void {
  this.onTouch = fn;
}

// setDisabledState(isDisabled: boolean): void
// Sets disabled state for entire component
setDisabledState(isDisabled: boolean): void {
  this.disabled = isDisabled;
  if (this.disabled) {
    this.selectionControl.disable();
  } else {
    this.selectionControl.enable();
  }
}

Validation Integration

The component also implements NG_VALIDATORS:

// validate(control: AbstractControl): ValidationErrors | null
// Performs validation and returns errors if any
validate(control: AbstractControl): ValidationErrors | null {
  // Check min/max selection requirements
  // Return validation errors or null
  return { minRequired: true, maxExceeded: false };
}

Form Integration Examples

Reactive Forms

import { Component } from '@angular/core';
import { FormControl, FormGroup, Validators } from '@angular/forms';

@Component({
  selector: 'app-reactive-checkbox',
  template: `
    <form [formGroup]="checkboxForm">
      <app-checkbox-selection-input
        formControlName="selections"
        [data]="options"
        label="Select Options"
        [minSelection]="2"
        [maxSelection]="4"
        [disableMax]="true">
      </app-checkbox-selection-input>
      
      <div class="errors" *ngIf="checkboxForm.get('selections')?.errors">
        <div *ngIf="checkboxForm.get('selections')?.hasError('minRequired')">
          Please select at least 2 options
        </div>
        <div *ngIf="checkboxForm.get('selections')?.hasError('maxExceeded')">
          Maximum selections exceeded
        </div>
      </div>
    </form>
  `
})
export class ReactiveCheckboxComponent {
  checkboxForm = new FormGroup({
    selections: new FormControl([], [
      Validators.required,
      Validators.minLength(2),
      Validators.maxLength(4)
    ])
  });
  
  options = ['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5'];
}

Template-Driven Forms

import { Component } from '@angular/core';

@Component({
  selector: 'app-template-checkbox',
  template: `
    <form #checkboxForm="ngForm">
      <app-checkbox-selection-input
        [(ngModel)]="selectedValues"
        name="checkboxSelections"
        [data]="options"
        label="Template Driven Selection"
        [minSelection]="1"
        [maxSelection]="3"
        required>
      </app-checkbox-selection-input>
      
      <div *ngIf="checkboxForm.controls.checkboxSelections?.invalid && 
                   checkboxForm.controls.checkboxSelections?.touched">
        Please make a selection
      </div>
    </form>
  `
})
export class TemplateCheckboxComponent {
  selectedValues: string[] = [];
  
  options = ['Choice 1', 'Choice 2', 'Choice 3', 'Choice 4'];
}

Programmatic Control

// Setting values
this.formControl.setValue(['Option 1', 'Option 2']);
this.formControl.patchValue(['Option 1']); // Partial update

// Resetting
this.formControl.reset();

// Getting current value
const currentValue = this.formControl.value;

// Validation
const isValid = this.formControl.valid;
const errors = this.formControl.errors;

// Setting custom errors
this.formControl.setErrors({ customError: 'Custom error message' });

Validation System

Built-in Validation

The component provides built-in validation for:

Min Selection Validation

// Requires at least X selections
[minSelection]="2"  // Must select at least 2 items

Max Selection Validation

// Allows maximum X selections
[maxSelection]="3"  // Cannot select more than 3 items

Disable Max Behavior

// Auto-disable remaining checkboxes when max reached
[disableMax]="true"  // Disables unchecked boxes at max

Validation Error Types

| Error Type | Condition | Description | |------------|-----------|-------------| | minRequired | selectedCount < minSelection | Not enough selections made | | maxExceeded | selectedCount >= maxSelection | Too many selections made | | required | Control has required validator and no selections | Control is required but empty |

Custom Validation Examples

// Complex validation scenarios
const complexForm = new FormGroup({
  permissions: new FormControl([], [
    Validators.required,
    Validators.minLength(1),  // At least 1 selection
    Validators.maxLength(5),  // Maximum 5 selections
    customMaxValidator(3)     // Custom: Cannot select admin + delete together
  ])
});

// Custom validator example
function customMaxValidator(maxCount: number) {
  return (control: AbstractControl): ValidationErrors | null => {
    const value = control.value;
    if (value && value.length > maxCount) {
      return { customMaxExceeded: true };
    }
    return null;
  };
}

Module Configuration