Skip to content

Chip Field

A Vaadin Flow add-on that provides a chip/tag input field where users can select and manage a list of items as visual chips.

Overview

Use the Chip Field add-on when you need a multi-value input that presents selected items as dismissible chips — for example, selecting tags, roles, or categories. The component supports autocomplete from a predefined item set, optional creation of new items, and full integration with Vaadin's Binder for form binding.

Features

  • Generic ChipField<T> with customizable label generation via ItemLabelGenerator.
  • Autocomplete suggestions from a DataProvider or a fixed list.
  • Closable chips (user can remove individual chips).
  • Allow creation of new items not present in the data provider via NewItemHandler.
  • Server-side events: chip created, chip removed, chip clicked.
  • Full Binder support — getValue() returns List<T>.
  • Input validation with pattern and error message.
  • Read-only and required indicator support.
  • Theme and size customization via HasTheme and HasSize.

Supported versions

Add-on version Vaadin version
2.x 14–25

Installation

From the Vaadin Directory

Available in the Vaadin Directory.

Maven dependency

<dependency>
    <groupId>com.flowingcode.vaadin.addons.chipfield</groupId>
    <artifactId>chipfield-addon</artifactId>
    <version>X.Y.Z</version>
</dependency>

Replace X.Y.Z with the latest released version. Add the Vaadin add-ons repository to your pom.xml:

<repository>
    <id>vaadin-addons</id>
    <url>https://maven.vaadin.com/vaadin-addons</url>
</repository>

For snapshot builds, see maven.flowingcode.com/snapshots.

JavaDoc is published at javadoc.flowingcode.com.

Usage

Create a ChipField with a label and the available items:

import com.flowingcode.vaadin.addons.chipfield.ChipField;

// With a fixed list of strings
ChipField<String> chipField = new ChipField<>("Select planets",
    "Mercury", "Venus", "Earth", "Mars");
chipField.setClosable(true);

// Read the selected values
chipField.addValueChangeListener(e ->
    Notification.show("Selected: " + String.join(", ", e.getValue())));

Use a custom type with an ItemLabelGenerator:

ChipField<Planet> chipField = new ChipField<>(
    "Select planets",
    Planet::getName,
    Planet.MERCURY, Planet.VENUS, Planet.EARTH);
chipField.setClosable(true);

Supply items from a DataProvider:

ChipField<String> chipField = new ChipField<>("Tags");
chipField.setDataProvider(DataProvider.ofCollection(tags));

Allow users to create new items not present in the data provider:

chipField.setNewItemHandler(label -> new Tag(label));

Listen to chip events:

chipField.addChipCreatedListener(e ->
    Notification.show("Added: " + e.getChipLabel()));

chipField.addChipRemovedListener(e ->
    Notification.show("Removed: " + e.getChipLabel()));

chipField.addChipClickedListener(e ->
    Notification.show("Clicked: " + e.getChipLabel()));

Bind with Binder:

binder.forField(chipField).bind(MyBean::getTags, MyBean::setTags);

Add or remove items programmatically:

chipField.addSelectedItem("Jupiter");
chipField.removeSelectedItem("Venus");

Special configuration when using Spring

When running on Spring, allow-list the com.flowingcode package so Vaadin Flow can discover the add-on's components. See Common configuration for details.

API reference

Headline types exposed by the add-on:

  • ChipField<T> — the chip input component; extends AbstractField<ChipField<T>, List<T>> and implements HasDataProvider<T>, HasItemsAndComponents<T>, HasSize, HasStyle, and HasTheme.
  • ChipField(String label, T... availableItems) — creates a field using Object::toString as the label generator.
  • ChipField(String label, ItemLabelGenerator<T> itemLabelGenerator, T... availableItems) — creates a field with a custom label generator.
  • setAvailableItems(List<T> items) / setDataProvider(DataProvider<T, ?> dataProvider) — replace the available item set.
  • setChipLabelGenerator(ItemLabelGenerator<T>) — update the label generator after construction.
  • setNewItemHandler(SerializableFunction<String, T>) — enable new item creation; implicitly sets allowAdditionalItems to true.
  • setAllowAdditionalItems(boolean) / isAllowAdditionalItems() — control whether items outside the data provider are accepted.
  • setClosable(boolean) / isClosable() — show or hide the remove button on each chip.
  • setReadOnly(boolean) / isReadOnly() — toggle read-only mode.
  • setRequiredIndicatorVisible(boolean) / isRequiredIndicatorVisible() — toggle required indicator.
  • setValidationPattern(String) / getValidationPattern() — set an input validation regex.
  • setAllowedPattern(String) / getAllowedPattern() — restrict characters allowed in the input.
  • setValidationErrorMessage(String) / getValidationErrorMessage() — set the error message shown on validation failure.
  • validate() — trigger validation manually.
  • addSelectedItem(T) / removeSelectedItem(T) — programmatically add or remove a selected item.
  • getChipsAsStrings() — return the current selected values as a String[] using the label generator.

  • addChipCreatedListener(...) / addChipRemovedListener(...) / addChipClickedListener(...) — register chip event listeners; all return Registration.

  • ChipField.ChipEvent<T> — abstract base for chip events; provides getChipLabel() and getItem().

  • ChipField.ChipCreatedEvent<T> — fired when a chip is added.
  • ChipField.ChipRemovedEvent<T> — fired when a chip is removed.
  • ChipField.ChipClickedEvent<T> — fired when a chip is clicked.

For the full API surface, browse the published JavaDoc.

Demo

A live demo is available at addonsv25.flowingcode.com/chipfield. To run the demo locally:

git clone https://github.com/FlowingCode/ChipFieldAddon.git
cd ChipFieldAddon
mvn clean install jetty:run

Then open http://localhost:8080/.

Source code

ChipFieldAddon on GitHub — distributed under Apache License 2.0.