@stardyn/angular-ui-group-selector

Flexible and customizable group selector component with multi-level selection and view mode for Angular applications. Provides hierarchical checkbox trees with support for parent-child relationships and different themes.

Features

• Multi-level Selection: Support for nested groups with parent-child checkbox relationships
• View Mode: Dedicated component for displaying selected items in a clean view
• Theme Support: Dark, light, and red theme options
• Translation Support: Built-in translation callback support for internationalization
• Standalone Components: All components are standalone and can be used independently
• Form Integration: Full Angular Forms support with ControlValueAccessor
• TypeScript Support: Full TypeScript support with comprehensive type definitions
• Performance Focused: OnPush change detection strategy for optimal performance

Installation

npm install @stardyn/angular-ui-group-selector

Quick Start

1. Import Components

import { Component } from '@angular/core';
import { 
  XConUIGroupSelectorComponent,
  GroupSelectorView,
  XconUIGroupItem,
  XconUIGroupTheme
} from '@stardyn/angular-ui-group-selector';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    XConUIGroupSelectorComponent,
    GroupSelectorView
  ],
  template: `
    <xcon-ui-group-selector
      [items]="groupItems"
      [theme]="theme"
      [selectedKeys]="selectedKeys"
      (selectedKeysChange)="onSelectionChange($event)">
    </xcon-ui-group-selector>
    
    <xcon-ui-group-selector-view
      [items]="groupItems"
      [selectedKeys]="selectedKeys"
      [theme]="theme">
    </xcon-ui-group-selector-view>
  `
})
export class ExampleComponent {
  theme = XconUIGroupTheme.DARK;
  selectedKeys: string[] = [];
  
  groupItems: XconUIGroupItem[] = [
    {
      key: 'group1',
      label: 'Group 1',
      checked: false,
      children: [
        { key: 'item1', label: 'Item 1', checked: false },
        { key: 'item2', label: 'Item 2', checked: false }
      ]
    }
  ];
  
  onSelectionChange(keys: string[]) {
    this.selectedKeys = keys;
  }
}

2. Advanced Usage with Forms

import { FormControl, ReactiveFormsModule } from '@angular/forms';

@Component({
  imports: [XConUIGroupSelectorComponent, ReactiveFormsModule],
  template: `
    <form [formGroup]="form">
      <xcon-ui-group-selector
        formControlName="selectedItems"
        [items]="groupItems"
        [theme]="XconUIGroupTheme.LIGHT"
        [disabled]="form.get('selectedItems')?.disabled">
      </xcon-ui-group-selector>
    </form>
  `
})
export class FormExampleComponent {
  form = new FormGroup({
    selectedItems: new FormControl([])
  });
  
  groupItems: XconUIGroupItem[] = [
    {
      key: 'categories',
      label: 'Categories',
      checked: false,
      children: [
        {
          key: 'tech',
          label: 'Technology',
          checked: false,
          children: [
            { key: 'js', label: 'JavaScript', checked: false },
            { key: 'ts', label: 'TypeScript', checked: false }
          ]
        },
        {
          key: 'design',
          label: 'Design',
          checked: false,
          children: [
            { key: 'ui', label: 'UI Design', checked: false },
            { key: 'ux', label: 'UX Design', checked: false }
          ]
        }
      ]
    }
  ];
}

API Reference

XConUIGroupSelectorComponent

Main selector component with hierarchical checkbox tree.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | items | XconUIGroupItem[] | [] | Array of group items | | selectedKeys | string[] | [] | Array of selected item keys | | theme | XconUIGroupTheme | DARK | Theme for the component | | disabled | boolean | false | Disable all interactions | | translate | TranslateCallback | undefined | Translation function |

Events

| Event | Type | Description | |-------|------|-------------| | selectionChange | XconUIGroupItem[] | Emitted when selection changes | | itemChange | {item: XconUIGroupItem, checked: boolean} | Emitted when individual item changes | | selectedKeysChange | string[] | Emitted when selected keys change |

GroupSelectorView

View component for displaying selected items in a clean layout.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | items | XconUIGroupItem[] | [] | Array of group items | | selectedKeys | string[] | [] | Array of selected item keys | | theme | XconUIGroupTheme | DARK | Theme for the component | | showDescription | boolean | true | Show item descriptions | | showIcons | boolean | true | Show item icons | | emptyMessage | string | 'No items selected' | Message when no items selected | | selectedMessage | string | 'selected items' | Message for selected items count | | groupByParent | boolean | true | Group items by parent | | translate | TranslateCallback | undefined | Translation function |

XconUIGroupItem Interface

interface XconUIGroupItem {
  key: string;
  label: string;
  description?: string;
  icon?: string;
  checked: boolean;
  disabled?: boolean;
  children?: XconUIGroupItem[];
}

XconUIGroupTheme Enum

enum XconUIGroupTheme {
  DARK = 'dark',
  LIGHT = 'light',
  RED = 'red'
}

Translation Support

// Translation callback function
const translateCallback = async (key: string): Promise<string> => {
  // Your translation logic here
  return await translateService.get(key).toPromise();
};

// Usage in template
<xcon-ui-group-selector
  [translate]="translateCallback"
  [items]="items">
</xcon-ui-group-selector>

Themes

Dark Theme (Default)

theme = XconUIGroupTheme.DARK;

Light Theme

theme = XconUIGroupTheme.LIGHT;

Red Theme

theme = XconUIGroupTheme.RED;

Form Integration

The component implements ControlValueAccessor for seamless Angular Forms integration:

// Reactive Forms
form = new FormGroup({
  selection: new FormControl(['item1', 'item2'])
});

// Template-driven Forms
[(ngModel)]="selectedKeys"

Selection Behavior

• Leaf Selection: Only leaf nodes (items without children) contribute to the final selection
• Parent State: Parent checkboxes show checked/indeterminate state based on children
• Auto-update: Parent states automatically update when children change
• Key Management: Selected keys include both leaf items and parent groups with selected children

Performance

• OnPush Change Detection: All components use OnPush strategy for optimal performance
• Standalone Components: Tree-shakable components reduce bundle size
• Efficient Updates: Smart change detection prevents unnecessary re-renders
• Memory Optimized: Deep cloning only when necessary

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { 
  XConUIGroupSelectorComponent,
  GroupSelectorView,
  XconUIGroupItem,
  XconUIGroupTheme
} from '@stardyn/angular-ui-group-selector';

License

MIT License - see LICENSE file for details.

Repository

https://github.com/stardyn/angular-ui-group-selector