← Back

Time Column Renderers

Vaadin Grid column renderers to display java.time types: `Instant`, `OffsetDateTime`, and `ZonedDateTime`



Time Column Renderers is a non-visual component add-on for Vaadin Framework 8.1 and later for displaying additional java.time types.

Vaadin Grid 8.1 and later comes bundled with a pair of column renderers for displaying two of the modern date-time data types found in Java 8 and later:

  • LocalDateRenderer for displaying LocalDate objects
  • LocalDateTimeRenderer for displaying LocalDateTime objects.

These two java.time types purposely lack any concept of time zone or offset-from-UTC.

The java.time classes include three more types that do include a time zone or offset-from-UTC:

By default, Vaadin Grid calls the toString method on such objects to render a String for display. That toString method generates a string in standard ISO 8601 format such as 2017-01-23T01:23:45.678Z. To display the date-time values in other formats, use this add-on with its trio of column renderers appropriately named: InstantRenderer, OffsetDateTimeRenderer, and ZonedDateTimeRenderer. Specify a DateTimeFormatter with ZoneId and Locale to adjust zones and localize.

The API of these renderer classes follows the pattern of the API of the classes published by Vaadin Ltd. Note that I do not agree with their decision to provide constructors taking a String representing a custom formatting pattern. Other constructors take a DateTimeFormatter object, and that should suffice. The column renderers should not, in my opinion, get involved in processing a calling programmer’s custom formatting pattern codes. And these extra constructors complicate the API of these classes with no added benefit. See my feature request # 10,207 to remove these constructors from their API. If deprecated there, I will do so here.

Hopefully, such classes as these renderers will be added to Vaadin itself in a future update. See feature request # 10,208.

Sample code

grid.addColumn( Person:: getWhenInstant )
    .setCaption( "When" )
        new InstantRenderer( 
                .ofLocalizedDateTime( FormatStyle.LONG )
                .withZone( ZoneId.of( "America/Montreal" ) )
                .withLocale( Locale.CANADA_FRENCH )
package com.example.timecolrentest;

import javax.servlet.annotation.WebServlet;

import com.vaadin.annotations.Theme;
import com.vaadin.annotations.VaadinServletConfiguration;
import com.vaadin.server.VaadinRequest;
import com.vaadin.server.VaadinServlet;
import com.vaadin.ui.*;
import org.basilbourque.timecolumnrenderers.InstantRenderer;

import java.time.Instant;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.time.format.FormatStyle;
import java.util.AbstractMap;
import java.time.temporal.ChronoUnit;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;

 * Example app showing the use of the "Time Column Renderers" Add-On component.
 * <p>
 * This example shows the `InstantRenderer` for displaying `Instant` objects. 
 * The add-on component also provides renderers for display `OffsetDateTime` and `ZonedDateTime` objects.
@Theme ( "mytheme" )
public class MyUI extends UI
    public static final long serialVersionUID = 201710251700L;

    protected void init ( VaadinRequest vaadinRequest )
        final VerticalLayout layout = new VerticalLayout( );

        Person person1 = new Person( "Alice" , ) );  // Class 'Person' defined below.
        Person person2 = new Person( "Bob" , ).plus( 1 , ChronoUnit.HOURS ) );
        Person person3 = new Person( "Mallory" , ).plus( 2 , ChronoUnit.HOURS ) );
        List < Person > persons = new ArrayList <>( 3 );
        persons.add( person1 );
        persons.add( person2 );
        persons.add( person3 );

        Grid < Person > grid = new Grid <>( );
        grid.setCaption( "People" );
        grid.setItems( persons );
        grid.addColumn( Person:: getName ).setCaption( "Name" );
        grid.addColumn( Person:: getWhen )
                .setCaption( "When" )
                        new InstantRenderer(                                          // Apply this Add-On component’s `InstantRenderer` if you want some format other than standard ISO 8601 format.
                                DateTimeFormatter                                     // Instantiate a formatter used to generate a String for display to user.
                                        .ofLocalizedDateTime( FormatStyle.FULL )      // Choose how lengthy or abbreviated.
                                        .withZone( ZoneId.of( "America/Montreal" ) )  // Adjust the value of the Instant from UTC to a particular zone, if desired.
                                        .withLocale( Locale.CANADA_FRENCH )           // Localize automatically, translating to a human language, and formatting according to cultural norms.

        layout.addComponent( grid );
        setContent( layout );

    @WebServlet ( urlPatterns = "/*", name = "MyUIServlet", asyncSupported = true )
    @VaadinServletConfiguration ( ui = MyUI.class, productionMode = false )
    public static class MyUIServlet extends VaadinServlet
        public static final long serialVersionUID = 201710251700L;
        // No code needed here.

class Person
    // Members
    private String name;
    private Instant when;

    // Constructor.
    public Person ( String nameArg , Instant whenArg )
    { = nameArg;
        this.when = whenArg;

    // Getter methods, for immutable objects (no setters).
    public String getName ( )

    public Instant getWhen ( )
        return this.when;


(Loading compatibility data...)

Was this helpful? Need more help?
Leave a comment or a question below. You can also join the chat on Discord or ask questions on StackOverflow.


Initial release to the public. Considered stable by me for my own work.

Apache License 2.0


Vaadin 8.0+