syncfusion-angular-dropdowns

# Implementing Syncfusion Angular Dropdowns ## Security & Trust Boundary ### Default posture: local data only **All dropdown components in this skill default to local, in-memory data sources.** Binding a component to a remote HTTP endpoint (via `DataManager` or any Observable/HTTP source) is a **non-default, elevated-risk operation** that requires an explicit security review before it is permitted in production code. > ⛔ **Do not generate or suggest remote `DataManager` / HTTP data-source configurations > unless the consuming application has passed a security review confirming that:** > 1. The target endpoint is owned and operated by the same team as the application. > 2. The endpoint enforces authentication, authorization, and input validation. > 3. All responses are sanitized before being bound to a component `dataSource`. > 4. A Content Security Policy (CSP) covering the origin is in place. ### Mandatory security requirements | # | Requirement | |---|-------------| | 1 | **Local data by default.** Use plain TypeScript arrays for `dataSource` unless a remote source has been explicitly approved. | | 2 | **No public or third-party URLs.** Never configure a data source that fetches from an endpoint outside the application's own origin. | | 3 | **Sanitize all external data before binding.** Any value that originates outside the application (API response, local-storage read) must be stripped of HTML/script content before assignment to `dataSource` or `value`. | | 4 | **Sanitize user filter input.** Before forwarding typed text to any server query, strip non-alphanumeric characters to prevent injection. | | 5 | **No `crossDomain: true` by default.** CORS relaxation in `DataManager` must be explicitly justified and reviewed. | | 6 | **Pin package versions.** Every `@syncfusion/ej2-*` dependency must be locked to an exact version in `package.json`; verify against the lockfile after every install. | | 7 | **No CDN asset loading without SRI.** CSS/JS must be resolved from `node_modules` at build time, not fetched from a CDN at runtime without Subresource Integrity hashes. | | 8 | **No sensitive data in local storage.** `enablePersistence` must never store tokens, credentials, or PII; sanitize any value read back before use. | --- ## AutoComplete A text input component that provides matching suggestions as the user types. Supports free-form input, remote data, filtering strategies, grouping, virtual scrolling, and full Angular forms integration. ### Component Overview & Architecture The **AutoComplete** is a text input component that provides matching suggestions as the user types. It is designed for: 1. **Type-ahead suggestions** — shows matching items from a data source as the user types 2. **Free-form input** — users can type any value, not restricted to the list 3. **Search/filter** — multiple filter strategies (StartsWith, Contains, EndsWith) 4. **Autofill** — automatically completes the first matched suggestion in the input 5. **Grouped suggestions** — categorize items by a `groupBy` field 6. **Virtual scrolling** — efficiently handles thousands of items 7. **Template customization** — item, group, header, footer, and empty-state templates ### Key Characteristics | Aspect | Details | |--------|---------| | **Selection** | Single item; user can also type any free-form value | | **Data Sources** | Local arrays, remote DataManager, OData, Web API, Observable (async pipe) | | **Filtering** | Built-in filtering: `StartsWith`, `EndsWith`, `Contains` | | **Autofill** | Completes the first match inline as the user types | | **Performance** | Virtual scrolling for large datasets (1,000+ items) | | **Forms** | Template-driven (`ngModel`) and reactive (`FormControl`) form integration | | **Accessibility** | WCAG 2.2 compliant, full keyboard navigation, ARIA attributes | | **Customization** | Item, group, header, footer, noRecords, actionFailure templates; CSS theming | --- ### Documentation Navigation Guide #### 📄 Getting Started **Read:** [references/autocomplete-getting-started.md](references/autocomplete-getting-started.md) - Install `@syncfusion/ej2-angular-dropdowns` package - Set up Angular 21+ project with standalone components - Import `AutoCompleteModule` and required CSS themes - Create your first AutoComplete with basic data binding - Configure popup height, width, and placeholder - Enable two-way binding with `[(value)]` #### 📄 Data Binding **Read:** [references/autocomplete-data-binding.md](references/autocomplete-data-binding.md) - Bind to local arrays (strings, numbers, objects, complex objects) - Map `value`, `text`, and `iconCss` fields via `fields` property - Remote data using DataManager with OData, Web API adapters - Async pipe pattern for RxJS Observables - Object binding with `allowObjectBinding` - Preselecting values using the `value` property #### 📄 Filtering & Search **Read:** [references/autocomplete-filtering-and-search.md](references/autocomplete-filtering-and-search.md) - Configure `filterType` (StartsWith, Contains, EndsWith) - Limit suggestion count with `suggestionCount` - Minimum character threshold with `minLength` - Case-sensitive filtering with `ignoreCase` - Diacritics/accent-insensitive filtering with `ignoreAccent` - Debounce delay to optimize remote filtering with `debounceDelay` - Custom filtering via the `filtering` event with `updateData` #### 📄 Grouping & Templates **Read:** [references/autocomplete-grouping-and-templates.md](references/autocomplete-grouping-and-templates.md) - Group suggestions by category using `fields.groupBy` - Item templates for custom rendering - Group header templates (inline and fixed) - Header and footer templates for the popup - Empty state with `noRecordsTemplate` - Action failure template for remote data errors #### 📄 Feature Configuration **Read:** [references/autocomplete-feature-configuration.md](references/autocomplete-feature-configuration.md) - Autofill: inline suggestion completion with `autofill` property - Highlight matched characters with `highlight` property - Disable individual items with `fields.disabled` or `disableItem` method - Disable entire component with `enabled` property - Resizable popup with `allowResize` - Virtual scrolling for large datasets with `enableVirtualization` - Show/hide popup button with `showPopupButton` - Show/hide clear button with `showClearButton` - RTL support with `enableRtl` - Sort order with `sortOrder` #### 📄 Form Support & Validation **Read:** [references/autocomplete-form-support-and-validation.md](references/autocomplete-form-support-and-validation.md) - Template-driven forms using `ngModel` and `FormsModule` - Reactive forms using `FormControl`, `FormGroup`, and `ReactiveFormsModule` - Binding and validation patterns - Pre-selecting values via form model #### 📄 Accessibility & Localization **Read:** [references/autocomplete-accessibility-and-localization.md](references/autocomplete-accessibility-and-localization.md) - WCAG 2.2, Section 508, and ADA compliance - Full keyboard shortcuts (Arrow keys, Tab, Enter, Escape, Alt+Down/Up) - ARIA attributes: `aria-haspopup`, `aria-expanded`, `aria-selected`, `aria-autocomplete` - Screen reader support and focus management - Localization with `L10n.load()` for `noRecordsTemplate` and `actionFailureTemplate` - RTL language support #### 📄 Advanced Patterns & How-To **Read:** [references/autocomplete-advanced-patterns-how-to.md](references/autocomplete-advanced-patterns-how-to.md) - Autofill feature with the `autofill` property - Highlight searched characters with the `highlight` property - Multi-field custom filtering with `Predicate` (filter by both Name and Code) - Icon support via `fields.iconCss` - Suggestion list on focus from browser local storage > ⚠️ **Security note:** Local storage is accessible to any JavaScript running on the same > origin and is a common XSS attack surface. Never store sensitive data (tokens, PII) in > local storage. Sanitize any values read from local storage before binding them to the > component's `dataSource` or `value`. - Custom search and highlight styling #### 📄 API Reference **Read:** [references/autocomplete-api.md](references/autocomplete-api.md) - Complete properties reference with types, defaults, and descriptions - All methods with signatures and usage - All events with payload types and handler examples --- ### Quick Start Example ```typescript // app.component.ts (Angular 21 Standalone) import { Component } from '@angular/core'; import { AutoCompleteModule } from '@syncfusion/ej2-angular-dropdowns'; @Component({ selector: 'app-root', standalone: true, imports: [AutoCompleteModule], template: ` <ejs-autocomplete id="sports" [dataSource]="sportsData" placeholder="Find a sport" [(value)]="selectedValue"> </ejs-autocomplete> ` }) export class AppComponent { public sportsData: string[] = [ 'Badminton', 'Basketball', 'Cricket', 'Football', 'Golf', 'Hockey', 'Tennis' ]; public selectedValue: string = ''; } ``` **Install the package:** > ⚠️ **Security note:** Pin the package to a specific version to prevent unintended upgrades > to potentially compromised releases. Verify the installed version against your lockfile > (`package-lock.json` / `yarn.lock`) after installation. ```bash ng add @syncfusion/ej2-angular-dropdowns@<version> ``` **Add CSS (styles.css):** > ⚠️ **Security note:** These imports are resolved from `node_modules` at build time. > Ensure the installed Syncfusion packages match your pinned versions in `package-lock.json` > or `yarn.lock` before building. Do not source these files from a CDN without > Subresource Integrity (SRI) hashes. ```css @import '../node_modules/@syncfusion/ej2-base/styles/material3.css'; @import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css'; @import '../node_modules/@syncfusion/ej2-dropdowns/styles/material3.css'; @import '../node_modules/@syncfusion/ej2-lists/styles/material3.css'; @import '../node_modules/@syncfusion/ej2-popups/styles/material3.css'; ``` --- ### Common Patterns #### Pattern 1: Filter with Complex Object Data ```typescript // Map fields for object array public fields: Object = { value: 'Game' }; public sportsData: { [key: string]: Object }[] = [ { Id: 'Game1', Game: 'Badminton' }, { Id: 'Game2', Game: 'Cricket' } ]; ``` ```html <ejs-autocomplete [dataSource]="sportsData" [fields]="fields" placeholder="Find a game"> </ejs-autocomplete> ``` **When to use:** Whenever your data is an array of objects and you need to display one field as the suggestion text. --- #### Pattern 2: Autofill + Highlight ```html <ejs-autocomplete [dataSource]="data" [autofill]="true" [highlight]="true" filterType="StartsWith"> </ejs-autocomplete> ``` **When to use:** Search bars where users expect inline completion and visual emphasis on matched text. --- #### Pattern 3: Remote Data with Debounce > 🔒 **Security policy — remote data is a restricted pattern.** > Binding AutoComplete to a remote endpoint requires a security review (see > [Security & Trust Boundary](#security--trust-boundary) above) before use in production. > Remote data binding details and requirements are documented in > [references/autocomplete-data-binding.md](references/autocomplete-data-binding.md). > **No remote `DataManager` example is provided here by default.** **When to use:** API-backed autocomplete where you want to reduce request frequency — only after the endpoint and data pipeline have been reviewed per the security requirements above. --- #### Pattern 4: Virtual Scrolling for Large Datasets ```typescript import { AutoCompleteComponent, VirtualScroll } from '@syncfusion/ej2-angular-dropdowns'; AutoCompleteComponent.Inject(VirtualScroll); ``` ```html <ejs-autocomplete [dataSource]="records" [fields]="fields" [enableVirtualization]="true" popupHeight="200px"> </ejs-autocomplete> ``` **When to use:** Datasets with 1,000+ items where rendering all DOM elements at once is costly. --- ### Key Properties Quick Reference | Property | Type | Default | Purpose | |----------|------|---------|---------| | `dataSource` | Array \| DataManager | `[]` | Source data for suggestions | | `fields` | FieldSettingsModel | `{ value: null }` | Map data columns to component | | `placeholder` | string | `null` | Hint text when empty | | `value` | string \| number \| boolean \| object | `null` | Selected/typed value | | `filterType` | FilterType | `'Contains'` | How suggestions are matched | | `minLength` | number | `1` | Minimum chars to trigger suggestions | | `suggestionCount` | number | `20` | Max suggestions shown | | `autofill` | boolean | `false` | Inline completion of first match | | `highlight` | boolean | `false` | Highlight matched characters | | `ignoreCase` | boolean | `true` | Case-insensitive filtering | | `ignoreAccent` | boolean | — | Ignore diacritics in filtering | | `debounceDelay` | number | `300` | Delay (ms) before filtering fires | | `enableVirtualization` | boolean | `false` | Virtual scroll for large data | | `allowResize` | boolean | `false` | Resizable popup | | `showClearButton` | boolean | `true` | Show ✕ to clear value | | `showPopupButton` | boolean | `false` | Show dropdown toggle button | | `enabled` | boolean | `true` | Enable/disable entire component | | `readonly` | boolean | `false` | Prevent user edits | | `allowObjectBinding` | boolean | `false` | Bind value as full object | | `sortOrder` | SortOrder | `null` | Sort suggestions (Ascending/Descending) | | `popupHeight` | string \| number | `'300px'` | Popup list height | | `popupWidth` | string \| number | `'100%'` | Popup list width | | `locale` | string | `'en-US'` | Localization culture | | `enableRtl` | boolean | `false` | Right-to-left rendering | --- ### Workflow Decision Tree ``` Need to implement AutoComplete? │ ├─ What's your data source? │ ├─ Local array → See Data Binding: "Array of string" or "Array of object" │ └─ Remote API → See Data Binding: "Bind to remote data" │ ├─ How should filtering work?