` to the template
- Basic data binding with `[dataSource]`
- Popup height/width configuration
- Two-way binding with `[(value)]`
#### Data Binding
📄 **Read:** [references/dropdownlist-data-binding.md](references/dropdownlist-data-binding.md)
- 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
📄 **Read:** [references/dropdownlist-filtering.md](references/dropdownlist-filtering.md)
- 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
📄 **Read:** [references/dropdownlist-templates.md](references/dropdownlist-templates.md)
- 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
📄 **Read:** [references/dropdownlist-grouping-and-virtualization.md](references/dropdownlist-grouping-and-virtualization.md)
- 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
📄 **Read:** [references/dropdownlist-disabled-items-and-forms.md](references/dropdownlist-disabled-items-and-forms.md)
- 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
📄 **Read:** [references/dropdownlist-customization-and-styling.md](references/dropdownlist-customization-and-styling.md)
- 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
📄 **Read:** [references/dropdownlist-how-to.md](references/dropdownlist-how-to.md)
- 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
📄 **Read:** [references/dropdownlist-api.md](references/dropdownlist-api.md)
- 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
```typescript
import { Component, OnInit } from '@angular/core';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';
@Component({
standalone: true,
imports: [DropDownListModule],
selector: 'app-root',
template: `
Selected: {{ selectedValue }}
`
})
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
```typescript
// Enable filtering in template
//
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](#security--trust-boundary)) before use in production.
> Remote data binding details and requirements are documented in
> [references/dropdownlist-data-binding.md](references/dropdownlist-data-binding.md).
> **No remote `DataManager` example is provided here by default.**
#### Reactive Form Integration
```typescript
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:
//
```
### Key Props
| Property | Type | Description |
|---|---|---|
| `dataSource` | `any[] \| DataManager` | Data for the list |
| `fields` | `FieldSettingsModel` | Maps text, value, groupBy, disabled, iconCss |
| `value` | `string \| number \| boolean \| object` | Selected value (supports two-way binding) |
| `placeholder` | `string` | Input placeholder text |
| `allowFiltering` | `boolean` | Enable search box in popup |
| `filterType` | `'contains' \| 'startsWith' \| 'endsWith'` | Filter match strategy |
| `enableVirtualization` | `boolean` | Virtual scrolling for large lists |
| `popupHeight` / `popupWidth` | `string \| number` | Popup dimensions |
| `enabled` | `boolean` | Enable/disable entire component |
| `allowObjectBinding` | `boolean` | Bind full object as value |
| `ignoreCase` | `boolean` | Case-insensitive filtering (default: true) |
| `ignoreAccent` | `boolean` | Diacritics-insensitive filtering |
| `debounceDelay` | `number` | Delay (ms) before filter triggers |
| `itemTemplate` | `string` | Template for list items |
| `valueTemplate` | `string` | Template for selected value display |
| `noRecordsTemplate` | `string` | Empty state message |
### Common Use Cases
**Form field with validation** → See [references/dropdownlist-disabled-items-and-forms.md](references/dropdownlist-disabled-items-and-forms.md)
**Large list (1000+ items)** → Enable `[enableVirtualization]="true"` — see [references/dropdownlist-grouping-and-virtualization.md](references/dropdownlist-grouping-and-virtualization.md)
**Country/State/City cascading** → See [references/dropdownlist-how-to.md](references/dropdownlist-how-to.md#cascading-dropdownlists)
**Custom item rendering** (icons, multi-column) → See [references/dropdownlist-templates.md](references/dropdownlist-templates.md)
**Remote API data** → See [references/dropdownlist-data-binding.md](references/dropdownlist-data-binding.md#binding-remote-data)
## ListBox
A list-based selection component enabling single or multi-item selection. Supports data binding, templates, drag-and-drop reordering and transfer, sorting, grouping, and comprehensive accessibility features.
### Component Overview
The Syncfusion ListBox is a high-performance dropdown list replacement with advanced features:
| Feature | Benefit |
|---------|---------|
| **Multiple Selection Modes** | Single, multiple, or checkbox selection |
| **Data Binding** | Local arrays, complex objects, or remote services |
| **Drag & Drop** | Reorder items or transfer between lists |
| **Customization** | Icons, templates, grouping, sorting |
| **Accessibility** | WCAG 2.2, screen readers, keyboard navigation |
| **Performance** | Efficient rendering with large datasets |
### Documentation Navigation Guide
#### Getting Started
📄 **Read:** [references/listbox-getting-started.md](references/listbox-getting-started.md)
- 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
📄 **Read:** [references/listbox-selection-modes.md](references/listbox-selection-modes.md)
- 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
📄 **Read:** [references/listbox-data-binding.md](references/listbox-data-binding.md)
- 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
📄 **Read:** [references/listbox-drag-and-drop-features.md](references/listbox-drag-and-drop-features.md)
- 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
📄 **Read:** [references/listbox-customization.md](references/listbox-customization.md)
- 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
📄 **Read:** [references/listbox-practical-examples.md](references/listbox-practical-examples.md)
- 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
📄 **Read:** [references/listbox-how-to-guides.md](references/listbox-how-to-guides.md)
- 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
📄 **Read:** [references/listbox-api.md](references/listbox-api.md)
- 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
```typescript
import { Component, OnInit } from '@angular/core';
import { ListBoxModule } from '@syncfusion/ej2-angular-dropdowns';
@Component({
imports: [ListBoxModule],
standalone: true,
selector: 'app-listbox',
template: `
`
})
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.
```css
/* 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 Ch
…(truncated)