Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Creating a simple component container

Components in Vaadin can be roughly split into two groups, Components and ComponentContainers. ComponentContainers are Components in themselves which can also contain other components. If you are about to implement a component that contains other components, then you’ll get a headstart by extending Vaadin’s ComponentContainer. The biggest feature is in transferring the list of server side components from your component to the client. Here’s how you do it.

Server Side

To start of we implement our server side component. For this we extend the ready made abstract implementation AbstractComponentContainer. This requires us to implement addComponent(Component), removeComponent(Component), replaceComponent(Component, Component), getComponentCount and getComponentIterator().

package com.example.widgetcontainer;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

import com.vaadin.ui.AbstractComponentContainer;
import com.vaadin.ui.Component;

public class WidgetContainer extends AbstractComponentContainer {

  List<Component> children = new ArrayList<Component>();

  public void addComponent(Component c) {

  public void removeComponent(Component c) {

  public void replaceComponent(Component oldComponent, Component newComponent) {
    int index = children.indexOf(oldComponent);
    if (index != -1) {
      children.add(index, newComponent);

  public int getComponentCount() {
    return children.size();

  public Iterator<Component> iterator() {
    return children.iterator();

Add, remove and replace are quite straight forward. In the class we upkeep a list of children internally, and these three methods modify them. Add and remove have ready made methods in the super class for notifying all event handlers that the children have changed and because of that we should make calls to the super methods after we have updated the list. In replaceComponent we have to call fireComponentDetachEvent(Component) and fireComponentAttachEvent(Component) to manually trigger these events. In all three methods we should also call markAsDirty as a last step to notify the client side that the children have changed.

The methods getComponentCount() and iterator() takes care of providing the required information that we need to the client side. Here they are simple delegate methods to the List’s size() and iterator().

Client Side

Next up, we want to set up a standard GWT widget which will be our component container’s client side widget. GWT in itself has a bunch of component containers in it. In GWT, these are called Panels. For this case I will start with a VerticalPanel. It is roughly the same as VerticalLayout in Vaadin. Down the road you want to edit this file to add features or even extend Widget to create a complete custom widget. For now extending VerticalPanel is enough and we’ll use that as-is.

package com.example.widgetcontainer.client.ui;


public class VWidgetContainer extends VerticalPanel {
  public static final String CLASSNAME = "v-widgetcontainer";

  public VWidgetContainer() {


Your widget’s Connector will transfer the components from the server side as child widgets to our widget. The connector will feed the children to the panel trough it’s standard API, namely add(Widget), remove(Widget) and clear();

Instead of going the standard route of extending AbstractComponentConnector as your connector, here we can take use of Vaadin’s internal features and extend AbstractComponentContainerConnector. Additionally to implementing the getWidget() -method from AbstractComponentConnector, we also have to supply the class with an implementation to a method called updateCaption(ComponentConnector). This method is there if we want the container to take care of the captions for all the components. We don’t need to take care of these captions in this example so we can leave the implementation empty.

The real benefit of extending AbstractComponentContainerConnector is that we can now extend a method called onConnectorHierarchyChange(ConnectorHierarchyChangeEvent). This method will be called every time that the server side calls markAsDirty() if the component hierarchy has been changed. From within it, we can call on getChildComponents to get a list of all the child components, and populate our widget with those.

package com.example.widgetcontainer.client.ui;

import java.util.List;

import com.example.widgetcontainer.WidgetContainer;
import com.vaadin.client.ComponentConnector;
import com.vaadin.client.ConnectorHierarchyChangeEvent;
import com.vaadin.client.ui.AbstractComponentContainerConnector;
import com.vaadin.client.ui.Connect;

public class WidgetContainerConnector extends
        AbstractComponentContainerConnector {

  public void onConnectorHierarchyChange(ConnectorHierarchyChangeEvent event) {
    List<ComponentConnector> children = getChildComponents();
    VWidgetContainer widget = getWidget();
    for (ComponentConnector connector : children) {

  public VWidgetContainer getWidget() {
    return (VWidgetContainer) super.getWidget();

  public void updateCaption(ComponentConnector connector) {

This implementation removes all the component’s in the widget and adds all that are returned from getChildComponents. An obvious optimization to these is to compare what is already in the widget and only add/remove/move those widgets that have changed.

Example Usage

Nothing left but to use the component! Compile the widgetset and check that the widgetset is in use in your web.xml. Here is a little stand-alone application that uses this component:

package com.example.widgetcontainer;

import java.util.Random;

import com.vaadin.terminal.WrappedRequest;
import com.vaadin.ui.Button;
import com.vaadin.ui.Button.ClickEvent;
import com.vaadin.ui.Button.ClickListener;
import com.vaadin.ui.CheckBox;
import com.vaadin.ui.Component;
import com.vaadin.ui.Label;
import com.vaadin.ui.UI;

public class WidgetcontainerUI extends UI {
  public void init(VaadinRequest request) {
    VerticalLayout layout = new VerticalLayout();

    Label label = new Label("Hello Vaadin user");
    final WidgetContainer widgetContainer = new WidgetContainer();
    widgetContainer.addComponent(new Label(
        "Click the button to add components to the WidgetContainer."));
    Button button = new Button("Add more components", new ClickListener() {
      public void buttonClick(ClickEvent event) {
        Random randomGenerator = new Random();
        int random = randomGenerator.nextInt(3);
        Component component;
        if (random % 3 == 0) {
          component = new Label("A new label");
        } else if (random % 3 == 1) {
          component = new Button("A button!");
        } else {
          component = new CheckBox("A textfield");