Syncfusion React Listview

Implementing Syncfusion React ListView

A comprehensive guide to implementing the Syncfusion React ListView component for displaying dynamic, interactive lists with advanced features like templating, filtering, selection, and data management.

When to Use This Skill

Use this skill when you need to:

• Display lists of items with rich templating and customization
• Implement single or multiple item selection
• Add, remove, or update list items dynamically
• Filter and search list data
• Create nested or grouped lists
• Handle user interactions (scroll, select, check)
• Apply custom animations and styling
• Support drag-and-drop operations
• Optimize performance with virtualization
• Implement data binding (local or remote)
• Add checkboxes or custom icons
• Provide accessibility features (WCAG 2.1)

Component Overview

The ListView component displays a collection of items in a scrollable, interactive list. It supports:

• Data Sources: Arrays, objects, DataManager, remote APIs
• Selection Modes: None, single, multiple, or checkbox-based
• Templates: Item templates, header templates, group templates
• Data Operations: Filtering, sorting, grouping, searching
• Performance: Virtual scrolling for 1000+ items
• Interactions: Click, select, scroll events
• Styling: Built-in themes, custom CSS, RTL support
• Accessibility: WCAG 2.1 Level AA compliant

Installation & Setup

Step 1: Install Syncfusion Packages

npm install @syncfusion/ej2-react-lists @syncfusion/ej2-base @syncfusion/ej2-data

Step 2: Import Required Modules

import { ListViewComponent } from '@syncfusion/ej2-react-lists';
// For additional features:
import { Inject, Virtualization } from '@syncfusion/ej2-react-lists';

Step 3: Import CSS

import '@syncfusion/ej2-react-lists/styles/material.css'; // or other themes

Quick Start Example

import React from 'react';
import { ListViewComponent } from '@syncfusion/ej2-react-lists';

export function BasicListView() {
  const data = [
    { id: '1', text: 'Item 1' },
    { id: '2', text: 'Item 2' },
    { id: '3', text: 'Item 3' }
  ];

  return (
    <ListViewComponent
      id="list"
      dataSource={data}
      fields={{ text: 'text', id: 'id' }}
    />
  );
}

Core Concepts

1. Data Binding

Local Array:

const items = ['Apple', 'Banana', 'Orange'];
<ListViewComponent dataSource={items} />

Object Array with Mapping:

const data = [
  { productId: 1, productName: 'Laptop', category: 'Electronics' },
  { productId: 2, productName: 'Desk', category: 'Furniture' }
];

<ListViewComponent
  dataSource={data}
  fields={{
    id: 'productId',
    text: 'productName',
    groupBy: 'category'
  }}
/>

2. Selection Handling

const handleSelect = (args) => {
  console.log('Selected item:', args.text, args.id);
};

<ListViewComponent
  dataSource={data}
  select={handleSelect}
/>

3. Item Management

• Add Items: addItem(data, fields?)
• Remove Items: removeItem(item)
• Update Items: Replace in dataSource and refresh
• Get Selection: getSelectedItems()

4. Templates

// Item Template
const itemTemplate = (props) => (
  <div className="e-list-wrapper">
    <span>{props.text}</span>
    <span className="e-list-content">{props.category}</span>
  </div>
);

<ListViewComponent
  dataSource={data}
  fields={fields}
  template={itemTemplate}
/>

Documentation & Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and imports
• Basic setup and first component
• CSS themes and styling
• Minimal working example
• Project structure

Data Binding & Rendering

📄 Read: references/data-binding-rendering.md

• Local array data sources
• Object mapping with fields
• Remote data with DataManager
• Query filtering on remote data
• Load on demand and pagination
• Dynamic data updates

Item Management (CRUD)

📄 Read: references/item-management.md

• Adding new items dynamically
• Removing items by reference
• Updating existing items
• Batch operations
• Finding items in list
• Managing nested list items

Selection & Filtering

📄 Read: references/selection-filtering.md

• Single item selection
• Multiple item selection
• Checkbox-based selection
• Programmatic selection
• Filtering list items
• Search functionality
• Selection events and callbacks

Templating & Customization

📄 Read: references/templating-customization.md

• Custom item templates (JSX, function, string)
• Header templates with headerTemplate
• Group header templates with groupTemplate
• Template data context and variables
• Dynamic templates based on device
• CSS customization with classes
• RTL template support

Advanced Features

📄 Read: references/advanced-features.md

• Grouping and sorting
• Nested lists with hierarchy (up to 3 levels)
• Checkbox state management
• Animations and effects
• Custom icons and image display
• Enable/disable item states
• Layout patterns for complex dashboards

Layout & Alignment Patterns ⭐ NEW

📄 Read: references/layout-alignment-patterns.md

• Patient Portal Pattern: ListView with Cards, Appointments, Prescriptions, Messages
• Appointments Dashboard: 3x2 Grid layout with filters, scheduler, analytics
• Monitoring Dashboard: 3x3 Grid layout with KPIs, alerts, tickets
• Fixing common alignment issues (scrolling, borders, spacing)
• Responsive grid layouts for mobile/tablet/desktop
• Complete code examples for each pattern

Performance & Virtualization

📄 Read: references/performance-virtualization.md

• Virtual scrolling for large datasets (1000+)
• Enabling virtualization
• Refresh item heights
• Memory optimization tips
• Combining with pagination
• Performance best practices
• Dataset size recommendations

API Reference & Properties

📄 Read: references/api-reference.md

• Complete property documentation
• Method signatures and parameters
• Event handler arguments
• Default values for all properties
• Property type specifications
• Usage examples for each API

Accessibility & Events

📄 Read: references/accessibility-events.md

• WCAG 2.1 compliance
• Keyboard navigation
• Screen reader support
• ARIA attributes
• Focus management
• Event lifecycle
• Event arguments and data

Common Patterns

Pattern 1: List with Selection

User clicks item → select event fires → update UI

const [selected, setSelected] = React.useState(null);

const handleSelect = (args) => {
  setSelected(args);
};

<ListViewComponent
  dataSource={items}
  select={handleSelect}
/>

Pattern 2: Add/Remove Items

const listViewRef = React.useRef(null);

const addItem = () => {
  listViewRef.current.addItem([{ text: 'New Item', id: Date.now() }]);
};

const removeItem = (item) => {
  listViewRef.current.removeItem(item);
};

<ListViewComponent ref={listViewRef} dataSource={items} />

Pattern 3: Filtered List

const [filteredData, setFilteredData] = React.useState(items);

const handleFilter = (searchText) => {
  const filtered = items.filter(item =>
    item.text.toLowerCase().includes(searchText.toLowerCase())
  );
  setFilteredData(filtered);
};

<ListViewComponent dataSource={filteredData} />

Pattern 4: Multiple Selection with Checkboxes

<ListViewComponent
  dataSource={items}
  showCheckBox={true}
  fields={{ id: 'id', text: 'text', isChecked: 'checked' }}
/>

Pattern 5: ListView in Card Container (NEW)

<div style={{