0
# Data Components
1

2
Vaadin's data components provide high-performance display and interaction with large datasets. These components support lazy loading, virtual scrolling, sorting, filtering, and selection.
3

4
## Core Imports
5

6
```java
7
// Data display components
8
import com.vaadin.flow.component.grid.Grid;
9
import com.vaadin.flow.component.treegrid.TreeGrid;
10
import com.vaadin.flow.component.virtuallist.VirtualList;
11

12
// Data providers and sources
13
import com.vaadin.flow.data.provider.DataProvider;
14
import com.vaadin.flow.data.provider.ListDataProvider;
15
import com.vaadin.flow.data.provider.CallbackDataProvider;
16
import com.vaadin.flow.data.provider.HierarchicalDataProvider;
17
import com.vaadin.flow.data.provider.TreeDataProvider;
18
import com.vaadin.flow.data.provider.TreeData;
19
import com.vaadin.flow.data.provider.Query;
20
import com.vaadin.flow.data.provider.QuerySortOrder;
21

22
// Selection models
23
import com.vaadin.flow.component.grid.GridSingleSelectionModel;
24
import com.vaadin.flow.component.grid.GridMultiSelectionModel;
25
import com.vaadin.flow.data.selection.SingleSelectionModel;
26
import com.vaadin.flow.data.selection.MultiSelectionModel;
27

28
// Renderers
29
import com.vaadin.flow.data.renderer.ComponentRenderer;
30
import com.vaadin.flow.data.renderer.LitRenderer;
31
import com.vaadin.flow.data.renderer.TextRenderer;
32
import com.vaadin.flow.data.renderer.NumberRenderer;
33
import com.vaadin.flow.data.renderer.LocalDateRenderer;
34
import com.vaadin.flow.data.renderer.LocalDateTimeRenderer;
35

36
// Core interfaces and utilities
37
import com.vaadin.flow.component.Component;
38
import com.vaadin.flow.component.HasSize;
39
import com.vaadin.flow.data.provider.HasDataProvider;
40
import com.vaadin.flow.function.ValueProvider;
41
import com.vaadin.flow.function.SerializablePredicate;
42
import com.vaadin.flow.shared.Registration;
43

44
// Grid specific enums and classes
45
import com.vaadin.flow.component.grid.Grid.SelectionMode;
46
import com.vaadin.flow.component.grid.Grid.Column;
47
import com.vaadin.flow.component.grid.ColumnTextAlign;
48
import com.vaadin.flow.component.grid.GridSortOrder;
49
import com.vaadin.flow.data.provider.SortDirection;
50
import com.vaadin.flow.component.grid.GridMultiSelectionModel.SelectAllCheckboxVisibility;
51

52
// Java standard library for data handling
53
import java.util.Set;
54
import java.util.List;
55
import java.util.Optional;
56
import java.util.stream.Stream;
57
import java.time.LocalDate;
58
import java.time.LocalDateTime;
59
```
60

61
## Grid Component
62

63
### Grid
64

65
High-performance data grid with columns, sorting, filtering, and selection capabilities.
66

67
```java { .api }
68
public class Grid<T> extends Component implements HasDataProvider<T>, HasSize {
69
    public Grid();
70
    public Grid(Class<T> beanType);
71
    public Grid(Class<T> beanType, boolean autoCreateColumns);
72

73
    // Column management
74
    public Grid.Column<T> addColumn(ValueProvider<T, ?> valueProvider);
75
    public Grid.Column<T> addColumn(ValueProvider<T, ?> valueProvider, String columnKey);
76
    public Grid.Column<T> addColumn(String propertyName);
77
    public Grid.Column<T> addComponentColumn(ValueProvider<T, Component> componentProvider);
78
    public Grid.Column<T> addComponentColumn(ValueProvider<T, Component> componentProvider, String columnKey);
79
    public List<Grid.Column<T>> getColumns();
80
    public Grid.Column<T> getColumnByKey(String columnKey);
81
    public void removeColumn(Grid.Column<T> column);
82
    public void removeColumnByKey(String columnKey);
83
    public void removeAllColumns();
84
    public void setColumnOrder(Grid.Column<T>... columns);
85
    public void setColumnOrder(String... columnKeys);
86

87
    // Data management
88
    public void setItems(Collection<T> items);
89
    public void setItems(T... items);
90
    public void setDataProvider(DataProvider<T, ?> dataProvider);
91
    public DataProvider<T, ?> getDataProvider();
92
    public void setPageSize(int pageSize);
93
    public int getPageSize();
94

95
    // Selection
96
    public void setSelectionMode(SelectionMode selectionMode);
97
    public SelectionMode getSelectionMode();
98
    public GridSingleSelectionModel<T> asSingleSelect();
99
    public GridMultiSelectionModel<T> asMultiSelect();
100
    public Set<T> getSelectedItems();
101
    public Registration addSelectionListener(SelectionListener<Grid<T>, T> listener);
102

103
    // Sorting
104
    public void sort(List<GridSortOrder<T>> order);
105
    public List<GridSortOrder<T>> getSortOrder();
106
    public Registration addSortListener(ComponentEventListener<SortEvent<Grid<T>, GridSortOrder<T>>> listener);
107

108
    // Appearance
109
    public void setRowStripes(boolean rowStripes);
110
    public boolean isRowStripes();
111
    public void setAllRowsVisible(boolean allRowsVisible);
112
    public boolean isAllRowsVisible();
113
    public void setVerticalScrollingEnabled(boolean enabled);
114

115
    // Details
116
    public void setDetailsVisibleOnClick(boolean detailsVisibleOnClick);
117
    public void setItemDetailsRenderer(Renderer<T> renderer);
118
    public void setDetailsVisible(T item, boolean visible);
119
    public boolean isDetailsVisible(T item);
120

121
    // Event handling
122
    public Registration addItemClickListener(ComponentEventListener<ItemClickEvent<T>> listener);
123
    public Registration addItemDoubleClickListener(ComponentEventListener<ItemDoubleClickEvent<T>> listener);
124
}
125

126
public static class Column<T> {
127
    // Header and footer
128
    public Column<T> setHeader(String text);
129
    public Column<T> setHeader(Component component);
130
    public Component getHeaderComponent();
131
    public Column<T> setFooter(String text);
132
    public Column<T> setFooter(Component component);
133

134
    // Sorting
135
    public Column<T> setSortable(boolean sortable);
136
    public boolean isSortable();
137
    public Column<T> setSortProperty(String... properties);
138
    public Column<T> setSortOrderProvider(SortOrderProvider provider);
139

140
    // Appearance
141
    public Column<T> setWidth(String width);
142
    public String getWidth();
143
    public Column<T> setFlexGrow(int flexGrow);
144
    public int getFlexGrow();
145
    public Column<T> setResizable(boolean resizable);
146
    public boolean isResizable();
147
    public Column<T> setFrozen(boolean frozen);
148
    public boolean isFrozen();
149
    public Column<T> setVisible(boolean visible);
150
    public boolean isVisible();
151

152
    // Text alignment
153
    public Column<T> setTextAlign(ColumnTextAlign textAlign);
154
    public ColumnTextAlign getTextAlign();
155

156
    // Auto-width
157
    public Column<T> setAutoWidth(boolean autoWidth);
158
    public boolean isAutoWidth();
159

160
    // Key and renderer
161
    public String getKey();
162
    public Column<T> setRenderer(Renderer<T> renderer);
163
    public Renderer<T> getRenderer();
164
}
165
```
166

167
### TreeGrid
168

169
Hierarchical data grid for displaying tree-structured data.
170

171
```java { .api }
172
public class TreeGrid<T> extends Grid<T> {
173
    public TreeGrid();
174
    public TreeGrid(Class<T> beanType);
175

176
    // Hierarchy management
177
    public void setTreeData(TreeData<T> treeData);
178
    public TreeData<T> getTreeData();
179
    public void setDataProvider(HierarchicalDataProvider<T, ?> dataProvider);
180
    public HierarchicalDataProvider<T, ?> getDataProvider();
181

182
    // Expand/collapse
183
    public void expand(T... items);
184
    public void collapse(T... items);
185
    public void expandRecursively(T... items);
186
    public void collapseRecursively(T... items);
187
    public boolean isExpanded(T item);
188
    public Set<T> getExpandedItems();
189

190
    // Hierarchy column
191
    public void addHierarchyColumn(ValueProvider<T, ?> valueProvider);
192
    public void addHierarchyColumn(String propertyName);
193
    public Grid.Column<T> getHierarchyColumn();
194

195
    // Event handling
196
    public Registration addExpandListener(ComponentEventListener<ExpandEvent<T, TreeGrid<T>>> listener);
197
    public Registration addCollapseListener(ComponentEventListener<CollapseEvent<T, TreeGrid<T>>> listener);
198
}
199
```
200

201
### VirtualList
202

203
High-performance virtualized list for displaying large datasets with custom item renderers.
204

205
```java { .api }
206
public class VirtualList<T> extends Component implements HasDataProvider<T>, HasSize {
207
    public VirtualList();
208

209
    // Data management
210
    public void setItems(Collection<T> items);
211
    public void setItems(T... items);
212
    public void setDataProvider(DataProvider<T, ?> dataProvider);
213
    public DataProvider<T, ?> getDataProvider();
214

215
    // Rendering
216
    public void setRenderer(ComponentRenderer<? extends Component, T> renderer);
217
    public ComponentRenderer<? extends Component, T> getRenderer();
218

219
    // Placeholder
220
    public void setPlaceholderItem(T placeholderItem);
221
    public T getPlaceholderItem();
222

223
    // Event handling
224
    public Registration addAttachListener(ComponentEventListener<AttachEvent> listener);
225
    public Registration addDetachListener(ComponentEventListener<DetachEvent> listener);
226
}
227
```
228

229
## Data Providers
230

231
### DataProvider Interface
232

233
Core interface for providing data to components with lazy loading support.
234

235
```java { .api }
236
public interface DataProvider<T, F> {
237
    // Data fetching
238
    Stream<T> fetch(Query<T, F> query);
239
    int size(Query<T, F> query);
240

241
    // Refresh operations
242
    void refreshAll();
243
    void refreshItem(T item);
244

245
    // Event handling
246
    Registration addDataProviderListener(DataProviderListener<T> listener);
247

248
    // Filtering
249
    DataProvider<T, F> withFilter(F filter);
250
    DataProvider<T, Void> withConfigurableFilter();
251

252
    // Conversion
253
    <C> DataProvider<C, F> map(ValueProvider<T, C> mapper);
254
}
255

256
public static class Query<T, F> {
257
    public int getOffset();
258
    public int getLimit();
259
    public Stream<QuerySortOrder> getSortOrders();
260
    public Optional<F> getFilter();
261
    public List<String> getInMemorySorting();
262
}
263
```
264

265
### ListDataProvider
266

267
In-memory data provider for collections with built-in sorting and filtering.
268

269
```java { .api }
270
public class ListDataProvider<T> extends AbstractDataProvider<T, SerializablePredicate<T>> {
271
    public ListDataProvider(Collection<T> items);
272
    public ListDataProvider(Stream<T> items);
273

274
    // Item management
275
    public Collection<T> getItems();
276
    public void refreshItem(T item);
277
    public void refreshAll();
278

279
    // Sorting
280
    public void setSortOrder(ValueProvider<T, ?> valueProvider, SortDirection direction);
281
    public void setSortOrder(SerializableComparator<T> comparator);
282
    public void setSortComparator(SerializableComparator<T> comparator);
283

284
    // Filtering
285
    public void setFilter(SerializablePredicate<T> filter);
286
    public void addFilter(SerializablePredicate<T> filter);
287
    public void removeFilter();
288
    public SerializablePredicate<T> getFilter();
289
}
290
```
291

292
### CallbackDataProvider
293

294
Backend data provider that uses callbacks for data fetching.
295

296
```java { .api }
297
public class CallbackDataProvider<T, F> extends AbstractDataProvider<T, F> {
298
    public CallbackDataProvider(SerializableFunction<Query<T, F>, Stream<T>> fetchCallback,
299
                               SerializableFunction<Query<T, F>, Integer> sizeCallback);
300

301
    // ID-based operations
302
    public CallbackDataProvider<T, F> withConfigurableFilter(SerializableBiFunction<Query<T, F>, F, Query<T, F>> filterConverter);
303
}
304
```
305

306
### HierarchicalDataProvider
307

308
Data provider interface for tree-structured data.
309

310
```java { .api }
311
public interface HierarchicalDataProvider<T, F> extends DataProvider<T, F> {
312
    // Hierarchy queries
313
    Stream<T> fetchChildren(HierarchicalQuery<T, F> query);
314
    int getChildCount(HierarchicalQuery<T, F> query);
315
    boolean hasChildren(T item);
316
}
317

318
public class TreeDataProvider<T> extends AbstractHierarchicalDataProvider<T, SerializablePredicate<T>> {
319
    public TreeDataProvider(TreeData<T> treeData);
320

321
    public TreeData<T> getTreeData();
322
    public void setFilter(SerializablePredicate<T> filter);
323
}
324
```
325

326
## Data Structures
327

328
### TreeData
329

330
Container for hierarchical data structure.
331

332
```java { .api }
333
public class TreeData<T> {
334
    public TreeData();
335

336
    // Item management
337
    public TreeData<T> addItem(T parent, T item);
338
    public TreeData<T> addItems(T parent, T... items);
339
    public TreeData<T> addItems(T parent, Collection<T> items);
340
    public TreeData<T> addRootItems(T... items);
341
    public TreeData<T> addRootItems(Collection<T> items);
342
    public boolean removeItem(T item);
343
    public void clear();
344

345
    // Hierarchy queries
346
    public List<T> getRootItems();
347
    public List<T> getChildren(T item);
348
    public T getParent(T item);
349
    public boolean contains(T item);
350
    public Stream<T> getChildren(T item);
351
}
352
```
353

354
## Selection Models
355

356
### Grid Selection Models
357

358
```java { .api }
359
public interface GridSingleSelectionModel<T> extends SingleSelectionModel<Grid<T>, T> {
360
    void select(T item);
361
    void deselect(T item);
362
    Optional<T> getSelectedItem();
363
    void setDeselectAllowed(boolean deselectAllowed);
364
    boolean isDeselectAllowed();
365
}
366

367
public interface GridMultiSelectionModel<T> extends MultiSelectionModel<Grid<T>, T> {
368
    void select(T item);
369
    void deselect(T item);
370
    void selectAll();
371
    void deselectAll();
372
    Set<T> getSelectedItems();
373
    void updateSelection(Set<T> addedItems, Set<T> removedItems);
374

375
    // Select all checkbox
376
    void setSelectAllCheckboxVisibility(SelectAllCheckboxVisibility visibility);
377
    SelectAllCheckboxVisibility getSelectAllCheckboxVisibility();
378
}
379
```
380

381
## Renderers
382

383
### Component Renderers
384

385
```java { .api }
386
public class ComponentRenderer<COMPONENT extends Component, ITEM> implements Renderer<ITEM> {
387
    public ComponentRenderer(SerializableFunction<ITEM, COMPONENT> componentFunction);
388
    public ComponentRenderer(SerializableFunction<ITEM, COMPONENT> componentFunction,
389
                           SerializableBiConsumer<COMPONENT, ITEM> itemConsumer);
390

391
    public static <ITEM> ComponentRenderer<Component, ITEM> of(SerializableFunction<ITEM, Component> componentFunction);
392
}
393

394
public class LitRenderer<SOURCE> implements Renderer<SOURCE> {
395
    public static <SOURCE> LitRenderer<SOURCE> of(String template);
396
    public LitRenderer<SOURCE> withProperty(String property, ValueProvider<SOURCE, ?> provider);
397
    public LitRenderer<SOURCE> withFunction(String functionName, SerializableConsumer<SOURCE> handler);
398
}
399

400
public class TextRenderer<SOURCE> implements Renderer<SOURCE> {
401
    public TextRenderer();
402
    public TextRenderer(ValueProvider<SOURCE, String> valueProvider);
403
    public TextRenderer(ValueProvider<SOURCE, String> valueProvider, String nullRepresentation);
404
}
405

406
public class NumberRenderer<SOURCE> extends TextRenderer<SOURCE> {
407
    public NumberRenderer(ValueProvider<SOURCE, Number> valueProvider);
408
    public NumberRenderer(ValueProvider<SOURCE, Number> valueProvider, String format);
409
    public NumberRenderer(ValueProvider<SOURCE, Number> valueProvider, String format, Locale locale);
410
}
411

412
public class LocalDateRenderer<SOURCE> extends TextRenderer<SOURCE> {
413
    public LocalDateRenderer(ValueProvider<SOURCE, LocalDate> valueProvider);
414
    public LocalDateRenderer(ValueProvider<SOURCE, LocalDate> valueProvider, String format);
415
    public LocalDateRenderer(ValueProvider<SOURCE, LocalDate> valueProvider, String format, Locale locale);
416
}
417

418
public class LocalDateTimeRenderer<SOURCE> extends TextRenderer<SOURCE> {
419
    public LocalDateTimeRenderer(ValueProvider<SOURCE, LocalDateTime> valueProvider);
420
    public LocalDateTimeRenderer(ValueProvider<SOURCE, LocalDateTime> valueProvider, String format);
421
    public LocalDateTimeRenderer(ValueProvider<SOURCE, LocalDateTime> valueProvider, String format, Locale locale);
422
}
423
```
424

425
## Common Types and Enums
426

427
```java { .api }
428
// Selection modes
429
public enum SelectionMode {
430
    SINGLE, MULTI, NONE
431
}
432

433
// Column alignment
434
public enum ColumnTextAlign {
435
    START, CENTER, END
436
}
437

438
// Sort direction
439
public enum SortDirection {
440
    ASCENDING, DESCENDING
441
}
442

443
// Grid sort order
444
public class GridSortOrder<T> {
445
    public GridSortOrder(Grid.Column<T> column, SortDirection direction);
446
    public Grid.Column<T> getSorted();
447
    public SortDirection getDirection();
448
}
449

450
// Query sort order
451
public class QuerySortOrder {
452
    public QuerySortOrder(String sorted, SortDirection direction);
453
    public String getSorted();
454
    public SortDirection getDirection();
455
}
456

457
// Select all checkbox visibility
458
public enum SelectAllCheckboxVisibility {
459
    VISIBLE, HIDDEN, DEFAULT
460
}
461

462
// Value provider interface
463
public interface ValueProvider<SOURCE, TARGET> extends SerializableFunction<SOURCE, TARGET> {
464
}
465
```
466

467
## Usage Examples
468

469
### Basic Grid with Bean Binding
470

471
```java
472
Grid<Person> grid = new Grid<>(Person.class);
473
grid.setColumns("firstName", "lastName", "email", "age");
474
grid.setItems(personService.findAll());
475

476
grid.addColumn(person -> person.getFullName()).setHeader("Full Name");
477
grid.addComponentColumn(person -> new Button("Edit")).setHeader("Actions");
478
```
479

480
### Grid with Custom Data Provider
481

482
```java
483
Grid<Person> grid = new Grid<>();
484
grid.addColumn(Person::getFirstName).setHeader("First Name");
485
grid.addColumn(Person::getLastName).setHeader("Last Name");
486

487
CallbackDataProvider<Person, Void> dataProvider = new CallbackDataProvider<>(
488
    query -> personService.fetch(query.getOffset(), query.getLimit()).stream(),
489
    query -> personService.count()
490
);
491

492
grid.setDataProvider(dataProvider);
493
```
494

495
### TreeGrid with Hierarchical Data
496

497
```java
498
TreeGrid<Department> treeGrid = new TreeGrid<>();
499
treeGrid.addHierarchyColumn(Department::getName).setHeader("Department");
500
treeGrid.addColumn(Department::getEmployeeCount).setHeader("Employees");
501

502
TreeData<Department> treeData = new TreeData<>();
503
treeData.addRootItems(rootDepartments);
504
rootDepartments.forEach(dept ->
505
    treeData.addItems(dept, dept.getSubDepartments())
506
);
507

508
treeGrid.setTreeData(treeData);
509
```
510

511
These data components provide efficient handling of large datasets with minimal memory footprint and excellent user experience through virtual scrolling and lazy loading.