Implementing Syncfusion Angular Dropdowns

Security & Trust Boundary

Default posture: local data only

DataManager

⛔ 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

dataSource

dataSource

value

crossDomain: true

DataManager

@syncfusion/ej2-*

package.json

node_modules

enablePersistence

AutoComplete

Component Overview & Architecture

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

StartsWith

EndsWith

Contains

ngModel

FormControl

Documentation Navigation Guide

📄 Getting Started

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

// 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 = '';
}

⚠️ 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.

ng add @syncfusion/ej2-angular-dropdowns@<version>

⚠️ 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.

@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

// Map fields for object array
public fields: Object = { value: 'Game' };
public sportsData: { [key: string]: Object }[] = [
  { Id: 'Game1', Game: 'Badminton' },
  { Id: 'Game2', Game: 'Cricket' }
];

<ejs-autocomplete [dataSource]="sportsData" [fields]="fields" placeholder="Find a game">
</ejs-autocomplete>

Pattern 2: Autofill + Highlight

<ejs-autocomplete
  [dataSource]="data"
  [autofill]="true"
  [highlight]="true"
  filterType="StartsWith">
</ejs-autocomplete>

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 above) before use in production. Remote data binding details and requirements are documented in references/autocomplete-data-binding.md. No remote

DataManager

example is provided here by default.

Pattern 4: Virtual Scrolling for Large Datasets

import { AutoCompleteComponent, VirtualScroll } from '@syncfusion/ej2-angular-dropdowns';
AutoCompleteComponent.Inject(VirtualScroll);

<ejs-autocomplete
  [dataSource]="records"
  [fields]="fields"
  [enableVirtualization]="true"
  popupHeight="200px">
</ejs-autocomplete>

Key Properties Quick Reference

dataSource

[]

fields

{ value: null }

placeholder

null

value

null

filterType

'Contains'

minLength

1

suggestionCount

20

autofill

false

highlight

false

ignoreCase

true

ignoreAccent

debounceDelay

300

enableVirtualization

false

allowResize

false

showClearButton

true

showPopupButton

false

enabled

true

readonly

false

allowObjectBinding

false

sortOrder

null

popupHeight

'300px'

popupWidth

'100%'

locale

'en-US'

enableRtl

false

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?
│   ├─ Default (Contains)   → No extra config needed
│   ├─ StartsWith           → filterType="StartsWith"
│   ├─ Custom multi-field   → See Advanced Patterns: "Custom filtering"
│   └─ Accent-insensitive   → [ignoreAccent]="true"
│
├─ Need autofill (inline completion)?
│   └─ YES → [autofill]="true" + filterType="StartsWith"
│
├─ Highlight matched text?
│   └─ YES → [highlight]="true"
│
├─ Large dataset (1,000+ items)?
│   └─ YES → [enableVirtualization]="true" + inject VirtualScroll
│
├─ Using inside a form?
│   ├─ Template-driven → See Form Support: "ngModel"
│   └─ Reactive        → See Form Support: "FormControl"
│
└─ Need accessibility or localization?
    └─ YES → See Accessibility & Localization reference

ComboBox

Component Overview & Architecture

1. Select from a list of predefined options
2. Enter custom values when

   allowCustom

   is enabled
3. Search/filter items as they type
4. Group items by category
5. Customize display with templates for items, groups, headers, footers

Key Characteristics

Documentation Navigation Guide

📄 Getting Started

• Install

  @syncfusion/ej2-angular-dropdowns

  package
• Set up Angular 21+ project with standalone components
• Import required modules and CSS themes
• Create your first ComboBox with minimal code
• Basic event handlers and configuration

📄 Data Binding & Sources

• Bind to local arrays (strings, numbers, objects)
• Map text and value fields for complex data
• Remote data from Web APIs, OData services
• DataManager configuration for different data adapters
• Async pipe for RxJS Observables
• Handling dynamic data updates

📄 Filtering & Search

• Enable filtering with

  allowFiltering

  property
• Configure filter types (StartsWith, Contains, EndsWith, etc.)
• Case-sensitive filtering for strict matching
• Diacritics filtering for accent-insensitive search
• Debounce delay to optimize remote requests
• Minimum filter character requirements
• Custom filtering with remote queries

📄 Grouping & Templates

• Group items by category using

  groupBy

  field
• Item templates for custom item rendering
• Group header templates (inline and fixed)
• Footer templates for additional information
• Combining multiple templates effectively
• Template performance optimization

📄 Advanced Feature Configuration

• Disable specific items or the entire component
• Read-only mode for display-only scenarios
• Virtual scrolling for thousands of items
• Dynamic resize behavior
• Allow custom values not in the list
• Styling and theme integration
• RTL support for Arabic/Hebrew

📄 Form Support & Validation

• Two-way binding with template-driven forms (ngModel)
• Reactive forms with FormControl and FormGroup
• Built-in and custom validators
• Form submission and validation state
• Disabled ComboBox in form context
• Error message display patterns

📄 Accessibility & Localization

• WCAG 2.2, Section 508, and ADA compliance
• Keyboard navigation shortcuts (arrow keys, Tab, Enter, Escape)
• Screen reader support with ARIA attributes
• Focus management and visual indicators
• Localization strings for different languages
• Right-to-left (RTL) language support

📄 Advanced Patterns & How-To Guides

• Autofill suggestions for autocomplete behavior
• Cascading ComboBoxes with dependent dropdowns
• Icons and emoji support in list items
• Resizable popup for better visibility
• Real-world patterns (search, live data, grouping)
• Performance optimization techniques

📄 API Reference

• Complete properties reference with types, defaults, and examples
• All methods with signatures, parameters, and usage examples
• All events with payload types and handler examples
• Notes on template syntax, two-way binding, and virtual scrolling
• Links to official Syncfusion documentation

Quick Start Example

Minimal Setup (5 minutes)

// app.component.ts
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ComboBoxComponent, ComboBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [CommonModule, ComboBoxModule],
  template: `
    <ejs-combobox
      [dataSource]="data"
      fields="{ text: 'text', value: 'id' }"
      placeholder="Select a language"
      [(ngModel)]="selectedValue">
    </ejs-combobox>
  `
})
export class AppComponent {
  selectedValue = '';
  data = [
    { id: '1', text: 'JavaScript' },
    { id: '2', text: 'TypeScript' },
    { id: '3', text: 'Angular' },
    { id: '4', text: 'React' }
  ];
}

1. Import

   ComboBoxComponent

   from

   @syncfusion/ej2-angular-dropdowns

2. Define data array with objects (id, text)
3. Use

   fields

   to map text and value fields
4. Bind selected value with

   [(ngModel)]

5. Set placeholder for empty state

Common Patterns & Workflows

Pattern 1: Autocomplete with Autofill

[autofill]="true"              // Auto-complete suggestions
[allowFiltering]="true"        // Enable typing
filterType="StartsWith"        // Match from beginning

Pattern 2: Cascading Dependent Dropdowns

// Country → State → City relationship
onCountryChange() {
  this.states = this.getStatesFor(country);
}

onStateChange() {
  this.cities = this.getCitiesFor(state);
}

Pattern 3: Grouped Items with Icons

fields = { 
  text: 'Name', 
  value: 'Id', 
  groupBy: 'Category',
  iconCss: 'Icon'
};

Pattern 4: Resizable Dropdown for Long Content

[allowResize]="true"           // Enable resize handle
itemTemplate="customTemplate"  // Show rich content

Key Props & Configuration

Essential Properties

dataSource

[]

fields

{ text, value }

placeholder

''

allowFiltering

false

allowCustom

false

readonly

false

enabled

true

[(ngModel)]

Advanced Properties

itemTemplate

groupTemplate

footerTemplate

enableVirtualization

groupBy

filterType

debounceDelay

Component Lifecycle

1. CREATE: Component initialized
   ↓
2. DATA BIND: dataSource loaded & displayed
   ↓
3. USER INTERACTION: typing, clicking, keyboard
   ↓
4. FILTER/SEARCH: items filtered based on input
   ↓
5. SELECT: user chooses item or enters custom value
   ↓
6. VALUE UPDATE: ngModel updates, events fire
   ↓
7. DESTROY: component cleaned up

• change

  : When selected value changes

• filtering

  : When user types (filter queries)

• select

  : When item is selected

• focus

  : When component gets focus

• blur

  : When component loses focus

Workflow Decision Tree

1. Do you have data to display?
   ├─ YES: Go to "Data Binding & Sources" reference
   └─ NO: Define your data array first

2. Do users need to search/filter?
   ├─ YES: Go to "Filtering & Search" reference
   └─ NO: allowFiltering = false (default)

3. Do you need to group items?
   ├─ YES: Go to "Grouping & Templates" reference
   └─ NO: Skip grouping configuration

4. Are you using a form?
   ├─ YES: Go to "Form Support & Validation" reference
   └─ NO: Use standalone ComboBox

5. Is accessibility required?
   ├─ YES: Go to "Accessibility & Localization" reference
   └─ NO: Still recommended for compliance

6. Performance issues with large datasets?
   ├─ YES: Enable virtual scrolling + pagination
   └─ NO: Standard rendering is fine

Next Steps

1. Start here: Getting Started - Set up your first ComboBox
2. Bind data: Data Binding & Sources - Connect to your data
3. Add search: Filtering & Search - Enable user filtering
4. Customize: Grouping & Templates - Style and organize display
5. Advanced: Advanced Patterns & How-To - Autofill, cascading, icons, resizing
6. Features: Feature Configuration - Enable advanced features
7. Integrate: Form Support - Connect to forms
8. Polish: Accessibility - Ensure compliance
9. Reference: API Reference - Full properties, methods, and events reference

Additional Resources

• Syncfusion Angular ComboBox API Reference
• Angular Version Support
• DataManager Documentation
• Component Themes & Styling

DropDownList

Documentation Navigation Guide

Getting Started

• Installation and Angular CLI setup
• Installing

  @syncfusion/ej2-angular-dropdowns

• CSS/theme imports for Material3
• Adding

  <ejs-dropdownlist>

  to the template
• Basic data binding with

  [dataSource]

• Popup height/width configuration
• Two-way binding with

  [(value)]

Data Binding

• Binding primitive arrays (strings, numbers)
• Binding arrays of objects with

  [fields]

  mapping
• Binding to nested/complex objects
• Remote data via

  DataManager

  (OData, Web API)
• Async pipe with Observable data streams
• Value binding (primitive and object types with

  allowObjectBinding

  )

Filtering

• Enabling search with

  [allowFiltering]

• Using the

  filtering

  event and

  updateData()

  method
• Minimum character threshold before filtering starts
• Filter types:

  contains

  ,

  startsWith

  ,

  endsWith

• Case-sensitive filtering
• Diacritics/accent-insensitive filtering
• Debounce delay for performance optimization

Templates

• Item template: customize each list item
• Value template: customize the selected value display
• Group template: customize group header appearance
• Header template: static element at popup top
• Footer template: static element at popup bottom
• No-records template: empty state display
• Action failure template: error state display

Grouping & Virtualization

• Grouping items with

  groupBy

  field
• Inline and fixed floating group headers
• Virtual scrolling with

  [enableVirtualization]

  for large lists
• Virtual scrolling with remote data
• Combining filtering and virtualization
• Customizing item count in virtual mode

Disabled Items & Forms

• Disabling specific items via

  fields.disabled

• Dynamic

  disableItem()

  method (by value, index, or element)
• Disabling the entire component with

  [enabled]="false"

• Template-driven forms with

  [(ngModel)]

• Reactive forms with

  FormControl

  and

  FormGroup

Customization & Styling

• CSS overrides for wrapper, icon, focus states
• Outline theme focus customization
• Popup appearance and list item styles
• Float label and placeholder styling
• Mandatory asterisk pattern
• Localization with

  L10n

  class
• RTL (right-to-left) support

How-To Recipes

• Add / remove / clear items dynamically
• Close popup programmatically
• Cascading DropDownLists
• Customize group header template
• Highlight filtered characters
• Incremental search behavior
• Modify remote data results
• Remote data item count display
• Tooltip on list items
• Value change event handling
• Icon support in list items

API Reference

• Complete properties reference with types, defaults, and usage examples
• All methods with signatures, parameters, and return types
• All events with argument interfaces and usage examples
• Interface details:

  FieldSettingsModel

  ,

  ChangeEventArgs

  ,

  SelectEventArgs

  ,

  PopupEventArgs

  ,

  FilteringEventArgs

• Quick-reference summary tables for properties, methods, and events

Quick Start Example

import { Component, OnInit } from '@angular/core';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [DropDownListModule],
  selector: 'app-root',
  template: `
    <ejs-dropdownlist
      id="ddl"
      [dataSource]="sports"
      [fields]="fields"
      placeholder="Select a sport"
      [(value)]="selectedValue"
      (change)="onChange($event)">
    </ejs-dropdownlist>
    <p>Selected: {{ selectedValue }}</p>
  `
})
export class AppComponent implements OnInit {
  public sports: { id: number; name: string }[] = [];
  public fields = { text: 'name', value: 'id' };
  public selectedValue: number = 2;

  ngOnInit() {
    this.sports = [
      { id: 1, name: 'Badminton' },
      { id: 2, name: 'Cricket' },
      { id: 3, name: 'Football' },
      { id: 4, name: 'Tennis' }
    ];
  }

  onChange(args: any) {
    this.selectedValue = args.value;
  }
}

Common Patterns

Searchable Dropdown

// Enable filtering in template
// <ejs-dropdownlist [allowFiltering]="true" (filtering)="onFilter($event)">
import { FilteringEventArgs } from '@syncfusion/ej2-angular-dropdowns';
import { Query } from '@syncfusion/ej2-data';

onFilter(args: FilteringEventArgs) {
  let query = new Query();
  query = args.text !== '' 
    ? query.where('name', 'contains', args.text, true) 
    : query;
  args.updateData(this.sports, query);
}

Remote Data Dropdown

🔒 Security policy — remote data is a restricted pattern. Binding DropDownList to a remote endpoint requires a security review (see Security & Trust Boundary) before use in production. Remote data binding details and requirements are documented in references/dropdownlist-data-binding.md. No remote

DataManager

example is provided here by default.

Reactive Form Integration

import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

// In component:
form = this.fb.group({ sport: ['Cricket', Validators.required] });
// In template:
// <form [formGroup]="form">
//   <ejs-dropdownlist formControlName="sport" [dataSource]="sports"></ejs-dropdownlist>
// </form>

Key Props

dataSource

any[] | DataManager

fields

FieldSettingsModel

value

string | number | boolean | object

placeholder

string

allowFiltering

boolean

filterType

'contains' | 'startsWith' | 'endsWith'

enableVirtualization

boolean

popupHeight

popupWidth

string | number

enabled

boolean

allowObjectBinding

boolean

ignoreCase

boolean

ignoreAccent

boolean

debounceDelay

number

itemTemplate

string

valueTemplate

string

noRecordsTemplate

string

Common Use Cases

[enableVirtualization]="true"

ListBox

Component Overview

Documentation Navigation Guide

Getting Started

• Installation and package setup
• Angular standalone vs NgModule patterns
• Basic component initialization
• CSS imports and theme selection
• Binding local data sources
• Running and testing the application

Selection Modes and Interactions

• Single item selection
• Multiple item selection with SHIFT/CTRL
• Checkbox selection mode
• Select all functionality
• Handling change events
• Getting selected items programmatically

Data Binding and Field Mapping

• Binding array of strings
• Binding array of objects
• Binding complex nested objects
• Remote data with DataManager and Query
• Field mapping (text, value, groupBy, iconCss)
• Troubleshooting data binding issues

Drag-and-Drop Features

• Single ListBox drag-and-drop reordering
• Dual ListBox drag-and-drop transfer
• Drag and drop events (dragStart, drag, drop)
• Scope configuration for multiple lists
• Event handling and item manipulation
• Real-world dual ListBox patterns

Customization and Styling

• Icons and iconCss field mapping
• Custom item templates
• Grouping items by category
• Sorting items (ascending/descending)
• CSS styling and theming
• Theme Studio integration
• Responsive design

Practical Implementation Examples

• Filtering ListBox items
• Form submission with selected items
• Enable/disable items conditionally
• Scroller for large datasets
• Real-world use cases
• Common troubleshooting scenarios

How-To Guides and Common Tasks

• Add items programmatically
• Select items programmatically
• Enable or disable items dynamically
• Enable scroller for large datasets
• Filter ListBox data with input
• Submit selected items in forms

API Reference

• All component properties with types, defaults, and examples
• All public methods with parameter signatures and usage examples
• All events with event argument interfaces and handler patterns
• Interface definitions:

  FieldSettingsModel

  ,

  SelectionSettingsModel

  ,

  ToolbarSettingsModel

• Event arg interfaces:

  ListBoxChangeEventArgs

  ,

  DragEventArgs

  ,

  DropEventArgs

  ,

  BeforeItemRenderEventArgs

  ,

  FilteringEventArgs

  ,

  SourceDestinationModel

• Enum definitions:

  SelectionMode

  ,

  SortOrder

  ,

  FilterType

  ,

  ToolBarPosition

  ,

  CheckBoxPosition

Quick Start Example

Basic ListBox with Local Data

import { Component, OnInit } from '@angular/core';
import { ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  imports: [ListBoxModule],
  standalone: true,
  selector: 'app-listbox',
  template: `
    <ejs-listbox 
      [dataSource]="items"
      [selectionSettings]="{ mode: 'Multiple' }">
    </ejs-listbox>
  `
})
export class ListBoxComponent implements OnInit {
  public items: { [key: string]: Object }[] = [];

  ngOnInit(): void {
    this.items = [
      { text: 'Option 1', id: '1' },
      { text: 'Option 2', id: '2' },
      { text: 'Option 3', id: '3' }
    ];
  }
}

With Styles

⚠️ 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.

/* In your global styles.css */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-dropdowns/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';
@import '@syncfusion/ej2-lists/styles/material3.css';

Common Patterns

Selection with Change Event

import { ListBoxChangeEventArgs } from '@syncfusion/ej2-dropdowns';

selectedValues: string[] = [];

onSelectionChange(args: ListBoxChangeEventArgs): void {
  this.selectedValues = args.value as string[];
}

<ejs-listbox
  [dataSource]="items"
  (change)="onSelectionChange($event)">
</ejs-listbox>

Dual ListBox for Transfer

sourceItems = [
  { text: 'Available Item 1', id: '1' },
  { text: 'Available Item 2', id: '2' }
];

selectedItems = [];

<div style="display: flex; gap: 20px;">
  <div>
    <h4>Available Items</h4>
    <ejs-listbox
      [dataSource]="sourceItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
  
  <div>
    <h4>Selected Items</h4>
    <ejs-listbox
      [dataSource]="selectedItems"
      allowDragAndDrop="true"
      scope="transfer-list">
    </ejs-listbox>
  </div>
</div>

Filtered ListBox

allItems = [
  { text: 'Apple', category: 'Fruit' },
  { text: 'Carrot', category: 'Vegetable' },
  { text: 'Banana', category: 'Fruit' }
];

get filteredItems() {
  return this.allItems.filter(item => 
    item.text.toLowerCase().includes(this.searchTerm.toLowerCase())
  );
}

Key Props

Selection Configuration

• selectionSettings

  :

  { mode: 'Single' | 'Multiple', showCheckbox: boolean, showSelectAll: boolean, checkboxPosition: 'Left' | 'Right' }

  > Note: When using

  showCheckbox: true

  , you must inject

  CheckBoxSelection

  :

  typescript

  import { ListBoxComponent, CheckBoxSelection, ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';
  ListBoxComponent.Inject(CheckBoxSelection);
  @Component({ imports: [ListBoxModule] })
  ```- **`maximumSelectionLength`**: Limit how many items can be selected

• value

  : Get or set selected values (

  string[] | number[] | boolean[]

  )

Data and Display

• dataSource

  : Array or DataManager with items

• fields

  :

  { text, value, groupBy, iconCss, disabled, htmlAttributes }

• itemTemplate

  : Template for rendering each list item

• noRecordsTemplate

  : Template shown when no items match

Interactions

• allowDragAndDrop

  : Enable drag-and-drop reordering/transfer

• scope

  : Identify related ListBoxes for drag-drop transfer

• allowFiltering

  : Show built-in filter search bar

• filterBarPlaceholder

  : Placeholder text for the filter bar

• filterType

  :

  'StartsWith' | 'EndsWith' | 'Contains'

• toolbarSettings

  : Configure toolbar buttons for dual-ListBox transfer

Appearance

• height

  : Height of the ListBox

• sortOrder

  :

  'None' | 'Ascending' | 'Descending'

• enabled

  : Enable/disable component

• enableRtl

  : Right-to-left rendering

• cssClass

  : Additional CSS class

Next Steps

1. Get Started: Read references/listbox-getting-started.md for setup instructions
2. Choose Selection Mode: Review references/listbox-selection-modes.md for your use case
3. Bind Data: See references/listbox-data-binding.md for data source options
4. Add Interactions: Explore references/listbox-drag-and-drop-features.md for advanced features
5. Customize: Check references/listbox-customization.md for styling options
6. See Examples: Review references/listbox-practical-examples.md for real-world implementations
7. API Reference: Consult references/listbox-api.md for the complete properties, methods, events, and interface definitions

Common Use Cases

• Selection Forms: Multi-select dropdown replacement
• Transfer Lists: Move items between lists (dual ListBox)
• Categories: Group-based item organization
• Filtering: Filter large datasets
• Data Display: Show structured list data
• Accessibility: Compliant selection interfaces

Mention

@

Component Overview & Architecture

@

div[contenteditable]

textarea

1. User tagging — tag people, teams, or resources using

   @

2. Hashtag suggestions — use any custom character (

   #

   ,

   /

   , etc.) as the trigger
3. Rich text integration — works with

   contenteditable

   divs and editors
4. Data binding — supports local arrays (strings, objects, complex objects) and remote DataManager sources
5. Filtering —

   Contains

   ,

   StartsWith

   ,

   EndsWith

   with configurable min-length, debounce, and spacing
6. Template customization — item, display, no-records, spinner, and group templates
7. Disabled items — mark individual list items as non-selectable
8. Accessibility — WCAG 2.2 compliant with full keyboard navigation and ARIA attributes

Key Characteristics

mentionChar

@

HTMLElement

target

DataManager

Contains

StartsWith

EndsWith

minLength

allowSpaces

showMentionChar

suffixText

L10n.load()

noRecordsTemplate

Documentation Navigation Guide

📄 Getting Started

• Install

  @syncfusion/ej2-angular-dropdowns

  package
• Set up Angular 21+ project with standalone components
• Import

  MentionModule

  and required CSS themes
• Create a target

  contenteditable

  div
• Bind

  target

  and basic

  dataSource

• Display/customize the mention character with

  showMentionChar

  and

  mentionChar

📄 Data Binding

• Bind to local arrays of strings, JSON objects, and complex objects
• Map

  text

  ,

  value

  ,

  groupBy

  , and

  iconCss

  via

  fields

  property
• Remote data binding (restricted — requires security review; see Security & Trust Boundary)
• Use the

  query

  property to scope remote requests

📄 Filtering

• Control filter strategy with

  filterType

  (

  Contains

  ,

  StartsWith

  ,

  EndsWith

  )
• Set minimum input length before triggering with

  minLength

• Allow spaces in the middle of a mention search with

  allowSpaces

• Limit visible suggestion count with

  suggestionCount

• Tune debounce delay for remote sources with

  debounceDelay

📄 Templates

• Customize suggestion list item layout with

  itemTemplate

• Customize the inserted text representation with

  displayTemplate

• Handle empty results with

  noRecordsTemplate

• Show a loading indicator while fetching remote data with

  spinnerTemplate

• Customize grouped items with

  groupTemplate

📄 Customization

• Show/hide the trigger character alongside selected text with

  showMentionChar

• Append a suffix (space, newline) after selection with

  suffixText

• Resize the popup with

  popupHeight

  and

  popupWidth

• Change the trigger character with

  mentionChar

• Control leading space requirement with

  requireLeadingSpace

• Apply custom CSS classes with

  cssClass

• Highlight searched characters with

  highlight

• Configure

  ignoreCase

  and

  ignoreAccent

  for search behavior

📄 Sorting & Disabled Items

• Sort suggestions with

  sortOrder

  (

  None

  ,

  Ascending

  ,

  Descending

  )
• Mark items as non-selectable via

  fields.disabled

• Dynamically disable items at runtime using the

  disableItem

  method

📄 Accessibility & Localization

• WCAG 2.2, Section 508, and ADA compliance
• Full keyboard shortcuts (Arrow Down/Up, Enter, Tab, Escape)
• ARIA attributes:

  aria-selected

  ,

  aria-activedescendent

  ,

  aria-owns

• Localize

  noRecordsTemplate

  with

  L10n.load()

• RTL support with

  enableRtl

📄 API Reference

• Complete properties reference with types, defaults, and descriptions
• All methods:

  addItem

  ,

  disableItem

  ,

  getDataByValue

  ,

  getItems

  ,

  hidePopup

  ,

  showPopup

  ,

  search

  ,

  destroy

• All events:

  dataBound

  ,

  actionFailureTemplate

Quick Start Example

// app.component.ts (Angular 21 Standalone)
import { Component } from '@angular/core';
import { MentionModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [MentionModule],
  template: `
    <label style="font-size: 15px; font-weight: 600;">Comments</label>
    <div id="mentionElement"
         placeholder="Type @ and tag a user"
         style="min-height: 100px; border: 1px solid #D7D7D7; border-radius: 4px; padding: 8px;">
    </div>
    <ejs-mention [dataSource]="userData" [target]="mentionTarget"></ejs-mention>
  `
})
export class AppComponent {
  public userData: string[] = ['Selma Rose', 'Garth', 'Robert', 'William', 'Joseph'];
  public mentionTarget: string = '#mentionElement';
}

⚠️ 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.

ng add @syncfusion/ej2-angular-dropdowns@<version>

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.

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-lists/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-angular-dropdowns/styles/material3.css';

Common Patterns

Pattern 1: Object Data with Field Mapping

public userData: { [key: string]: Object }[] = [
  { Name: 'Selma Rose', EmailId: 'selma@gmail.com' },
  { Name: 'Maria', EmailId: 'maria@gmail.com' },
  { Name: 'Robert', EmailId: 'robert@gmail.com' }
];
public fields: Object = { text: 'Name' };
public mentionTarget: string = '#mentionElement';

<ejs-mention [dataSource]="userData" [fields]="fields" [target]="mentionTarget"></ejs-mention>

Pattern 2: Custom Trigger Character with showMentionChar

<ejs-mention
  [dataSource]="userData"
  [target]="mentionTarget"
  [mentionChar]="'#'"
  [showMentionChar]="true">
</ejs-mention>

Pattern 3: Remote Data with Popup Width

🔒 Security policy — remote data is a restricted pattern. Binding Mention to a remote endpoint requires a security review (see Security & Trust Boundary) before use in production. Remote data binding details and requirements are documented in references/mention-data-binding.md. No remote

DataManager

example is provided here by default.

Pattern 4: Allow Spaces in Mention Search

<ejs-mention
  [dataSource]="userData"
  [fields]="fields"
  [allowSpaces]="true"
  [target]="mentionTarget">
</ejs-mention>

Key Properties Quick Reference

target

dataSource

[]

fields

{ text: null, value: null }

mentionChar

'@'

showMentionChar

false

suffixText

null

filterType

'Contains'

minLength

0

allowSpaces

false

suggestionCount

25

debounceDelay

300

sortOrder

'None'

popupHeight

'300px'

popupWidth

'auto'

highlight

false

ignoreCase

true

ignoreAccent

requireLeadingSpace

true

cssClass

null

locale

'en-US'

enableRtl

false

enablePersistence

false

zIndex

1000

Workflow Decision Tree

Need to implement Mention / @mention tagging?
│
├─ What's your data source?
│   ├─ Local strings/array  → See Data Binding: "Array of simple data"
│   ├─ Local objects        → See Data Binding: "Array of JSON data" + fields mapping
│   └─ Remote API           → See Data Binding: "Binding remote data"
│
├─ Custom trigger character (not @)?
│   └─ YES → [mentionChar]="'#'" (or any single char)
│
├─ Show trigger char in inserted text?
│   └─ YES → [showMentionChar]="true"
│
├─ Multi-word names (e.g., "John Doe")?
│   └─ YES → [allowSpaces]="true"
│
├─ Custom item layout in popup?
│   └─ YES → See Templates: itemTemplate / displayTemplate
│
├─ Need sorted suggestions?
│   └─ YES → See Sorting & Disabled Items: sortOrder
│
├─ Some items should not be selectable?
│   └─ YES → See Sorting & Disabled Items: fields.disabled / disableItem
│
├─ Filtering behavior?
│   ├─ By default (Contains)  → No extra config
│   ├─ StartsWith / EndsWith  → filterType="StartsWith"
│   └─ Minimum typed chars    → [minLength]="3"
│
└─ Need accessibility or localization?
    └─ YES → See Accessibility & Localization reference

MultiSelect

ejs-multiselect

Component Overview

Default

Box

Delimiter

CheckBox

Documentation Navigation Guide

Getting Started

• Installation and package setup (

  ng add

  )
• CSS imports and theme configuration
• Basic

  <ejs-multiselect>

  in standalone Angular component
• Popup height/width configuration
• Angular version notes (standalone default in Angular 19+)

Data Binding & Value Binding

• Local arrays (strings, numbers, objects)

• fields

  mapping:

  text

  ,

  value

  ,

  groupBy

  ,

  iconCss

  ,

  disabled

• Remote data with DataManager (OData, Web API)
• Pre-selecting values programmatically
• Object binding with

  allowObjectBinding

Selection Modes, Chips & Item Control

• mode

  property: Default / Box / Delimiter / CheckBox
• CheckBox mode:

  CheckBoxSelection

  ,

  showSelectAll

  ,

  maximumSelectionLength

• Chip customization via

  tagging

  event
• Custom values with

  allowCustomValue

• Disabling specific items:

  fields.disabled

  ,

  disableItem()

• addTagOnBlur

  and

  changeOnBlur

  behaviors

Filtering

• Enabling

  allowFiltering

  +

  filtering

  event +

  updateData()

• filterType

  :

  startsWith

  ,

  contains

  ,

  endsWith

• Minimum character threshold before query fires
• Remote filtering with DataManager
• Case-insensitive matching

Templates

• itemTemplate

  — custom list item rendering with

  ng-template

• valueTemplate

  — customize chip/selected value display

• groupTemplate

  — custom group header content

• headerTemplate

  /

  footerTemplate

  — popup top/bottom

• noRecordsTemplate

  /

  actionFailureTemplate

Grouping & Cascading

• fields.groupBy

  — organize items into categories
• Fixed vs inline group headers

• enableGroupCheckBox

  for group-level Select All
• Cascading MultiSelect: parent

  change

  event → filter child data
• Country → State → City cascade pattern

Form Integration

• Template-driven forms:

  FormsModule

  ,

  ngModel

  , two-way binding
• Reactive forms:

  ReactiveFormsModule

  ,

  FormGroup

  ,

  FormControl

• formControlName

  usage and validation
• Required field and custom validator patterns

Advanced Features

• Virtualization for large datasets (

  enableVirtualization

  )
• Popup resize (

  allowResize

  , resize events)
• Icons in list items (

  iconCss

  field)
• Localization (

  L10n.load()

  , locale key overrides)
• Accessibility: WAI-ARIA, keyboard navigation, WCAG 2.2
• RTL support

API Reference

• Complete list of all properties with types and defaults
• All public methods with signatures, parameters, and return types
• All events with argument types and usage examples
• Module injection notes (

  CheckBoxSelectionService

  )

Quick Start

⚠️ 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.

ng add @syncfusion/ej2-angular-dropdowns@<version>

// app.component.ts — Standalone Angular 19+
import { Component } from '@angular/core';
import { MultiSelectModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [MultiSelectModule],
  selector: 'app-root',
  template: `
    <ejs-multiselect
      [dataSource]="skills"
      [fields]="fields"
      placeholder="Select skills"
      [(value)]="selectedSkills"
      (change)="onChange($event)">
    </ejs-multiselect>
  `
})
export class AppComponent {
  public skills = [
    { id: 1, name: 'Angular' },
    { id: 2, name: 'React' },
    { id: 3, name: 'TypeScript' },
    { id: 4, name: 'Node.js' },
  ];
  public fields = { text: 'name', value: 'id' };
  public selectedSkills: number[] = [1, 3]; // pre-select Angular & TypeScript

  onChange(args: any): void {
    this.selectedSkills = args.value;
  }
}

⚠️ 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.

/* styles.css */
@import '@syncfusion/ej2-base/styles/material3.css';
@import '@syncfusion/ej2-buttons/styles/material3.css';
@import '@syncfusion/ej2-inputs/styles/material3.css';
@import '@syncfusion/ej2-lists/styles/material3.css';
@import '@syncfusion/ej2-popups/styles/material3.css';
@import '@syncfusion/ej2-dropdowns/styles/material3.css';
@import '@syncfusion/ej2-angular-dropdowns/styles/material3.css';

Common Patterns

Checkbox Mode with Select All

import { MultiSelectModule, CheckBoxSelectionService } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [MultiSelectModule],
  providers: [CheckBoxSelectionService],
  template: `
    <ejs-multiselect
      [dataSource]="items"
      mode="CheckBox"
      [showSelectAll]="true"
      selectAllText="Select All"
      unSelectAllText="Unselect All"
      [maximumSelectionLength]="5">
    </ejs-multiselect>
  `
})

Filtering with Remote Data

🔒 Security policy — remote data is a restricted pattern. Binding MultiSelect to a remote endpoint requires a security review (see Security & Trust Boundary) before use in production. Remote filtering details and requirements are documented in references/multiselect-filtering.md. No remote

DataManager

example is provided here by default.

Reactive Form Integration

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

// In component:
public skillsControl = new FormControl([1, 3]); // pre-selected IDs

// In template:
// <ejs-multiselect [formControl]="skillsControl" [dataSource]="skills" [fields]="fields">
// </ejs-multiselect>

Key Props

dataSource

any[] | DataManager

fields

FieldSettingsModel

text

value

groupBy

disabled

iconCss

value

any[]

[(value)]

mode

string

Default

Box

Delimiter

CheckBox

allowFiltering

boolean

filterType

string

startsWith

contains

endsWith

showSelectAll

boolean

maximumSelectionLength

number

allowCustomValue

boolean

enableVirtualization

boolean

popupHeight

popupWidth

string

allowResize

boolean

placeholder

string

MultiColumn ComboBox

ejs-multicolumncombobox

Navigation Guide

Getting Started

• Installation and package setup (

  ng add @syncfusion/ej2-angular-multicolumn-combobox@<version>

  )

  ⚠️ 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.

• CSS/theme imports for Material and other themes
• Basic standalone component usage with

  <ejs-multicolumncombobox>

• Binding

  dataSource

  and

  fields

  properties
• Configuring

  <e-columns>

  and

  <e-column>

  child elements
• Popup height and width configuration (

  popupHeight

  ,

  popupWidth

  )

Columns Configuration

• Defining columns with

  field

  ,

  header

  ,

  width

• Setting text alignment with

  textAlign

• Using column

  template

  with

  ng-template

• Displaying boolean values as checkboxes with

  displayAsCheckBox

• Applying custom CSS attributes via

  customAttributes

• Custom column headers with

  headerTemplate

• Formatting values with

  format

Data Binding

• Binding local object arrays via

  dataSource

• Remote data binding (restricted — requires security review; see Security & Trust Boundary)
• Mapping

  fields

  :

  text

  ,

  value

  , and

  groupBy

• Using the

  query

  property to filter/limit remote results

Items and Display Configuration

• Setting pre-selected text with

  text

  property
• Setting pre-selected value with

  value

  property
• Setting selected item by index with

  index

  property
• Placeholder text with

  placeholder

• Float label behavior with

  floatLabelType

  (Never/Always/Auto)
• Adding HTML attributes via

  htmlAttributes

• Setting component width with

  width

• Configuring popup dimensions (

  popupWidth

  ,

  popupHeight

  )
• Show/hide clear button with

  showClearButton

• Applying custom CSS class with

  cssClass

• Disabled state with

  disabled

• Read-only mode with

  readonly

• Configuring grid settings (

  gridSettings

  :

  gridLines

  ,

  rowHeight

  ,

  enableAltRow

  )

Filtering

• Enable/disable filtering with

  allowFiltering

• Changing filter type with

  filterType

  (StartsWith/EndsWith/Contains)

Sorting

• Enable/disable sorting with

  allowSorting

• Setting initial sort order with

  sortOrder

  (None/Ascending/Descending)
• Sorting single vs. multiple columns with

  sortType

Grouping

• Grouping items using the

  groupBy

  field in

  fields

  property