Documentation versions (currently viewingVaadin 8)

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



In this quickstart, we are going to create a simple Vaadin application and use the Vaadin Spreadsheet add-on to open an existing Excel spreadsheet file.


In order to follow this tutorial, you will need the following tools/setup:

  • Command line Maven

  • JDK installed

  • IDE (optional)

Project setup

To start off, we need to create a new project where we can use Spreadsheet. We will use Maven to set up a project, which can later be imported into your favorite IDE. You can also use your IDE to generate a new maven project using the vaadin-archetype-application archetype, version 8.0.0. Execute the following command to create the project:

mvn archetype:generate -DarchetypeGroupId=com.vaadin  \
  -DarchetypeArtifactId=vaadin-archetype-application \

You will be asked a few questions for setting up the project. In the following, the suitable answers are given for going through this quickstart:

Define value for property 'groupId': : com.vaadin
Define value for property 'artifactId': : spreadsheet-quickstart
Define value for property 'version':  1.0-SNAPSHOT: : <return>
Define value for property 'package':  com.vaadin: : <return>
[INFO] Using property: themeName = mytheme
[INFO] Using property: uiName = MyUI
[INFO] Using property: widgetsetName = MyAppWidgetset
Confirm properties configuration:
groupId: com.vaadin
artifactId: spreadsheet-quickstart
version: 1.0-SNAPSHOT
package: com.vaadin
themeName: mytheme
uiName: MyUI
widgetsetName: MyAppWidgetset
Y: : <return>

Now you should have a generated project in a directory that you specified its name after the artifactId, for example, spreadsheet-quickstart. You can run the new project by issuing the following commands:

[command]#cd# spreadsheet-quickstart
[command]#mvn# jetty:run

The latter command will compile all sources and start a local web server. Wait until it prints out “Started Jetty Server” and navigate to http://localhost:8080 using your favorite browser.

In your browser, you should see a Click Me button. When you click it, the text “Thank you for clicking” should appear below it. Great, the application works! We can now move on to replace this button with a Spreadsheet! Stop the web server by pressing Ctrl+C in the window where you started it.

Let us first add the Vaadin Spreadsheet dependency to the project and compile the widget set. Open the pom.xml file and find the dependencies tag. Add the following dependency declaration just before the end tag (/dependencies):


It is recommended to use the latest version available, the version number can be checked at Vaadin Directory.

After this, we need to fetch a license for Vaadin Spreadsheet in order to be able to compile the widget set. You can get a free trial key from Vaadin Directory. Click the large orange “Free trial key” button to the right and copy and paste the key into a file named .vaadin.spreadsheet.developer.license in your home directory.

Now we have created a new project, added the Vaadin Spreadsheet add-on to it and can move on to create our spreadsheet.

Creating your first Spreadsheet

Let us replace the Button with a Spreadsheet. To this end, follow the following steps:

  1. Copy the existing file to the root of the project

  2. Create a new File instance

    File sampleFile = new File("Simple Invoice.xlsx");
  3. Use the sample file in Spreadsheet constructor

    Spreadsheet spreadsheet = null;
    try {
         spreadsheet = new Spreadsheet(sampleFile);
    } catch (IOException e) {
  4. Add the spreadsheet to the main layout


Open the com.vaadin.MyUI class and change the init method to the following:

private Spreadsheet spreadsheet = null;

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


private void initSpreadsheet(){
   File sampleFile = new File("Simple Invoice.xlsx");
   try {
       spreadsheet = new Spreadsheet(sampleFile);
   } catch (IOException e) {

Now run it by issuing mvn jetty:run on the command line and load http://localhost:8080 in your browser. You should see a Spreadsheet with the content of the sample file.

After this we are all done! The end result is a simple UI showing an Excel spreadsheet running in your browser. For examples, please see the on-line demo at