Styling Applications

Learn how to apply app-specific styling across application views and application-specific components and how to use images and icons.

Prerequisites

You should be familiar with Importing Style Sheets to the different Style Scopes in your application.

Styling Views and Application-specific Components

Your views and application-specific components are usually built by composing existing lower-level components. Styling these components is a little different from styling the internals of built-in components. See Styling Components for more information on styling built-in components.

Server-Side Views and Custom Components

Server-side views and custom components (Java), extending from Component, are rendered in the global style scope. You can apply traditional CSS styling techniques for them.

The most common technique is to add CSS classes to the components in the view and target those classes in your style sheets.

MyView.java

Expand code

@CssImport("./styles/my-view.css")
public class MyView extends VerticalLayout {
  public MyView() {
    addClassName("my-view");
    H1 heading = new H1("My View Title");
    heading.addClassName("heading");
    Paragraph text = new Paragraph("Thanks for stopping by. Not much to see here. Click the button below to go back to start.");
    Button backButton = new Button("Go Back");
    backButton.addClassName("back-button");
    add(heading, text, backButton);
  }
}

styles/my-view.css

Expand code

.heading {
  margin-top: 0;
}
p {
  /* Assuming we are using the Lumo theme. If not, fall back to 1.2em */
  font-size: var(--lumo-font-size-l, 1.2em);
}
.back-button {
  background-color: var(--lumo-shade-90pct);
}

Client-side Views, Templates and Components

Client-side view, templates, and components are usually authored using Polymer, extending PolymerElement. Polymer elements render their HTML template inside shadow DOM and create a new style scope.

The instructions in Styling Polymer Templates apply to client-side views.

If you wish to author your client-side views using some other technology (for example LitElement), refer to the styling instructions of that technology.

Using Images

Static images, which need to be accessible by the browser, should be placed in the /src/main/webapp/ folder. For Spring Boot -based projects use /src/main/resources/META-INF/resources/.

See Storing and Loading Resources for more information about how static resources are handled.

JavaJavaScriptCSS

In server-side views (Java), use the Image component.

StylingApplications.java

Expand code

Image image = new Image("context://my-image.png", "Alternative text");

Using Icons

In general, icons are not different from images, as they show a graphic on the page. For bitmap-based icons (JPG, PNG, WebP, etc.), follow the above instructions for using images.

Since icons have some additional requirements on top of images, such as the need to be able to change their size and color using CSS, they are usually created using the SVG vector format and embedded directly inside the resulting HTML, instead of being referenced via CSS background-image: url(icon.svg) or HTML <img src="icon.svg">.

Vaadin has a component specifically for showing SVG icons. In addition, Vaadin offers a large collection of icons for you to use (with both SVG and font formats).

Note, that SVG icons are considered as the best practice. Font icons have some well documented caveats, especially regarding screen reader usage.

JavaJavaScript

In server-side views (Java), use the Icon component. There are two ways to create an icon from the Vaadin Icons collection.

The Icon component can be used in all the same places as any other component. Some components, such as Button, have API specifically for using icons.

StylingApplications.java

Expand code

Icon edit = new Icon(VaadinIcon.EDIT);
Icon close = VaadinIcon.CLOSE.create();

The Lumo theme has its own set of icons (see Lumo Icons), which you can also use.

JavaJavaScript

StylingApplications.java

Expand code

Icon icon = new Icon("lumo", "clock");

Creating a Custom Icon Set

If you want to create your own set of icons to use, you first need to package the SVG icons into a bundle. That makes them usable in client-side views and the <iron-icon> component/element.

For server-side views, you can create a similar Enum as VaadinIcon to make it easy to use your custom icon set. See the implementation of Vaadin Icons for inspiration.