data-providers

name	data-providers
description	Guide Claude on using Vaadin 25 data providers efficiently for Grid, ComboBox, and other listing components. This skill should be used when the user asks to "load data into a grid", "use a data provider", "lazy load data", "paginate grid data", "filter a grid", "sort a grid", "use setItems", "use CallbackDataProvider", "bind a Spring service to a grid", "use setItemsPageable", or needs help with in-memory vs lazy data binding, filtering, sorting, or custom data providers in Vaadin Flow.
version	0.1.0

Vaadin Data Providers in Vaadin 25

Use the Vaadin MCP tools (search_vaadin_docs, get_component_java_api) to look up the latest documentation whenever uncertain about a specific API detail. Always set vaadin_version to "25" and ui_language to "java".

Two Approaches: In-Memory vs. Lazy Loading

In-memory — small datasets that fit in server memory

List<Person> people = personService.findAll();
grid.setItems(people);

Use when: the full dataset is small (hundreds to low thousands of items), or you've already loaded it for other reasons.

In-memory data supports client-side-like sorting and filtering through the ListDataView:

GridListDataView<Person> dataView = grid.setItems(people);
dataView.setFilter(p -> p.getAge() < 30);
dataView.setSortOrder(Person::getName, SortDirection.ASCENDING);

Lazy loading — large datasets loaded on demand

Only the visible portion of data is loaded. Filtering and sorting are delegated to the backend (typically a database).

With Spring (preferred — uses Pageable):

grid.setItemsPageable(personService::list);

// Service method signature:
public List<Person> list(Pageable pageable) {
    return repository.findAll(pageable).getContent();
}

setItemsPageable converts Grid's internal query into a Spring Pageable with offset, limit, and sort information. This integrates directly with Spring Data repositories.

Without Spring (generic callbacks):

grid.setItems(query ->
    personService.fetch(query.getOffset(), query.getLimit()).stream()
);

The callback receives a Query object with getOffset(), getLimit(), and getSortOrders().

Filtering

In-memory filtering

GridListDataView<Person> dataView = grid.setItems(allPeople);

filterField.addValueChangeListener(e ->
    dataView.setFilter(person ->
        person.getName().toLowerCase().contains(e.getValue().toLowerCase()))
);

Lazy filtering (backend-delegated)

Pass the filter value into your service callback:

// With Spring
GridLazyDataView<Person> dataView = grid.setItemsPageable(
    pageable -> personService.list(pageable, filterField.getValue())
);
filterField.setValueChangeMode(ValueChangeMode.LAZY);
filterField.addValueChangeListener(e -> dataView.refreshAll());

// Without Spring
grid.setItems(query ->
    personService.fetch(
        query.getOffset(),
        query.getLimit(),
        query.getSortOrders(),
        filterField.getValue()
    ).stream()
);
filterField.addValueChangeListener(e -> grid.getDataProvider().refreshAll());

Use ValueChangeMode.LAZY on the filter field — it waits for the user to pause typing before triggering, reducing backend calls.

Sorting

In-memory sorting

Columns with Comparable types are automatically sortable. Customize with a Comparator:

grid.addColumn(Person::getName)
    .setHeader("Name")
    .setComparator(Comparator.comparing(p -> p.getName().toLowerCase()));

Lazy sorting (backend-delegated)

Declare which columns are sortable:

grid.setSortableColumns("name", "email");  // by property name
// or per-column:
grid.addColumn(Person::getTitle).setKey("title").setSortable(true);

Then handle query.getSortOrders() in your callback. With setItemsPageable, sorting is handled automatically via the Pageable object.

ComboBox Lazy Loading

ComboBox supports lazy loading with built-in text filtering:

// With Spring
comboBox.setItemsPageable(productService::list);

// Service must accept filter string:
public List<Product> list(Pageable pageable, String filterString) { ... }

// Without Spring
comboBox.setItems(query ->
    personService.fetch(
        query.getOffset(),
        query.getLimit(),
        query.getFilter().orElse("")
    ).stream()
);

Providing Item Count

Without a count callback, Grid uses infinite scrolling (the scrollbar updates as more items are loaded). For a better UX, provide the count:

// With Spring
grid.setItemsPageable(personService::list, personService::count);

// Without Spring
grid.setItems(
    query -> personService.fetch(query.getOffset(), query.getLimit()).stream(),
    query -> personService.count()
);

If exact count is expensive, provide an estimate:

GridLazyDataView<Person> dataView = grid.setItems(fetchCallback);
dataView.setItemCountEstimate(1000);
dataView.setItemCountEstimateIncrease(500);

Updating Displayed Data

Refresh a single item

person.setEmail("[e-mail]");
dataView.refreshItem(person);  // updates just this row

Refresh all data

dataView.refreshAll();  // re-fetches everything

Mutating in-memory lists

GridListDataView<Person> dataView = grid.setItems(mutableList);
dataView.addItem(newPerson);
dataView.removeItem(oldPerson);

Item Identity

Components rely on hashCode() and equals() for item identity. These must be based on stable, unique properties (typically the database ID), not mutable fields:

@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;
    Person person = (Person) o;
    return id == person.id;  // stable identifier only
}

@Override
public int hashCode() {
    return Objects.hash(id);
}

With Lombok: use @EqualsAndHashCode(onlyExplicitlyIncluded = true) and @EqualsAndHashCode.Include on the ID field.

Reusing Data Binding Logic

Domain-specific Grid subclass

@SpringComponent
@Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE)
public class PersonGrid extends Grid<Person> {

    public PersonGrid(@Autowired PersonRepository repo) {
        super(Person.class);
        setItems(q -> repo.findAll(
            PageRequest.of(q.getPage(), q.getPageSize())).stream());
        setColumns("name", "email");
    }
}

Standalone DataProvider class

@SpringComponent
public class PersonDataProvider
        extends AbstractBackEndDataProvider<Person, String> {

    @Autowired
    private PersonRepository repo;

    @Override
    protected Stream<Person> fetchFromBackEnd(Query<Person, String> query) {
        String filter = query.getFilter().orElse("");
        return repo.findByNameContaining(filter,
            VaadinSpringDataHelpers.toSpringPageRequest(query)).stream();
    }

    @Override
    protected int sizeInBackEnd(Query<Person, String> query) {
        String filter = query.getFilter().orElse("");
        return (int) repo.countByNameContaining(filter);
    }
}

Best Practices

1. Use setItemsPageable with Spring — it handles offset/limit/sort conversion to Pageable automatically, integrating cleanly with Spring Data.
2. Use lazy loading for datasets over ~1000 items — in-memory is simpler but doesn't scale.
3. Always implement stable hashCode/equals — based on the entity's ID, not mutable fields. This is required for Grid to correctly track selections and updates.
4. Use ValueChangeMode.LAZY on filter fields — prevents excessive backend queries while the user is typing.
5. Provide a count callback when possible — it gives users a proper scrollbar and ability to jump to the end.
6. Call refreshAll() when filter/sort criteria change externally — the Grid doesn't automatically know when your filter field value changes.
7. Don't call getGenericDataView().getItems() on lazy data — it loads the entire dataset into memory, defeating the purpose of lazy loading.