Docs

Docs

Write HTML

Learn how to create HTML structure in Java using Vaadin’s built-in HTML element classes.

Vaadin provides Java classes for standard HTML elements — Div, Span, Paragraph, headings, lists, links, and more. You use these to build the structural and textual parts of your UI in plain Java, without writing any HTML. These HTML element classes are full Vaadin components, so you can freely mix them with Vaadin UI components like Button, Text Field, and Grid — nesting them inside each other in any combination. This article covers the most common classes. For the full list, see the HTML Elements reference.

Copy-Paste into Your Project

A self-contained view that demonstrates the most common HTML element classes:

Source code
Java
import com.vaadin.flow.component.html.Anchor;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.H1;
import com.vaadin.flow.component.html.H2;
import com.vaadin.flow.component.html.Hr;
import com.vaadin.flow.component.html.ListItem;
import com.vaadin.flow.component.html.OrderedList;
import com.vaadin.flow.component.html.Paragraph;
import com.vaadin.flow.component.html.Span;
import com.vaadin.flow.component.html.UnorderedList;
import com.vaadin.flow.router.Route;

@Route("html-example")
public class HtmlExampleView extends Div {

    public HtmlExampleView() {
        H1 title = new H1("My Page");

        Paragraph intro = new Paragraph(
                "This page demonstrates Vaadin's HTML element classes.");

        H2 featuresHeading = new H2("Features");
        UnorderedList features = new UnorderedList(
                new ListItem("Type-safe Java API"),
                new ListItem("No HTML templates needed"),
                new ListItem("Full server-side control"));

        H2 stepsHeading = new H2("Getting Started");
        OrderedList steps = new OrderedList(
                new ListItem("Create a view class"),
                new ListItem("Add HTML elements"),
                new ListItem("Run the application"));

        Paragraph footer = new Paragraph();
        footer.add(new Span("Read the "));
        footer.add(new Anchor(
                "https://vaadin.com", "full documentation"));
        footer.add(new Span(" to learn more."));

        Hr divider = new Hr();

        add(title, intro, featuresHeading, features,
                stepsHeading, steps, divider, footer);
    }
}

Text and Structure

The most commonly used HTML element classes are:

  • Div — a generic block container (<div>)

  • Span — an inline container (<span>)

  • Paragraph — a block of text (<p>)

  • H1 through H6 — headings (<h1> through <h6>)

  • Hr — a horizontal rule (<hr>)

  • Pre — preformatted text (<pre>)

Set text content through the constructor or with setText():

Source code
Java
Paragraph p = new Paragraph("Hello, world!");

Span label = new Span();
label.setText("Status: OK");

Div, Paragraph, and headings are block elements — they stack vertically by default. Span is an inline element — it flows with the surrounding text.

Text set through setText() or the constructor is automatically escaped by Vaadin. It is always rendered as plain text, never interpreted as HTML. This means you can safely pass user input to these methods without risk of cross-site scripting (XSS).

Nesting Elements

All container elements support add() for building hierarchy:

Source code
Java
Div card = new Div();
card.add(new H2("Card Title"));
card.add(new Paragraph("Card content goes here."));

You can also nest components directly in the constructor:

Source code
Java
Div card = new Div(
        new H2("Card Title"),
        new Paragraph("Card content goes here."));

To mix text and child components in the same element, use add() with Span elements for the text portions:

Source code
Java
Paragraph p = new Paragraph();
p.add(new Span("This is "));
p.add(new Anchor("https://vaadin.com", "a link"));
p.add(new Span(" inside a paragraph."));
Note
 setText() replaces all content, including child components. To combine text and components, use add() with Span elements instead of setText().

Use Anchor for external links:

Source code
Java
Anchor link = new Anchor("https://vaadin.com", "Vaadin website");

Open links in a new tab by setting the target:

Source code
Java
Anchor link = new Anchor("https://vaadin.com", "Vaadin website");
link.setTarget("_blank");

For internal navigation within your application, use RouterLink instead of Anchor. It navigates without a full page reload:

Source code
Java
RouterLink link = new RouterLink("Go to dashboard", DashboardView.class);

See Navigate to a View for more on routing and RouterLink.

Lists

Use UnorderedList and OrderedList with ListItem elements:

Source code
Java
UnorderedList list = new UnorderedList(
        new ListItem("First item"),
        new ListItem("Second item"),
        new ListItem("Third item"));
Source code
Java
OrderedList steps = new OrderedList(
        new ListItem("Open the project"),
        new ListItem("Add a view"),
        new ListItem("Run the application"));

List items can contain any component, not only text:

Source code
Java
ListItem item = new ListItem();
item.add(new Span("Visit "));
item.add(new Anchor("https://vaadin.com", "vaadin.com"));

Semantic Elements

Vaadin provides classes for semantic HTML elements that help structure your page and improve accessibility:

  • Header — introductory content or navigation (<header>)

  • Footer — footer content (<footer>)

  • Nav — navigation links (<nav>)

  • Main — dominant page content (<main>)

  • Section — a standalone section (<section>)

  • Article — self-contained content (<article>)

  • Aside — tangentially related content (<aside>)

Source code
Java
Main main = new Main();
main.add(new H1("Dashboard"));
main.add(new Section(new H2("Sales"), salesChart));
main.add(new Aside(new H2("Quick Links"), linkList));

Semantic elements work like Div but convey meaning to browsers and assistive technologies.

Raw HTML

The Html component injects a raw HTML string into the page:

Source code
Java
Html content = new Html(
        "<div><strong>Bold</strong> and <em>italic</em></div>");

The HTML fragment must have exactly one root element. Its content is sent directly to the browser and cannot be modified after creation.

Warning
 Unlike setText() and add(), the Html component does not escape its content. The raw HTML string is sent directly to the browser as-is. You are responsible for sanitizing any user input before passing it to Html. Failing to do so creates a cross-site scripting (XSS) vulnerability.

When to Use HTML Elements vs. Components

Use the HTML element classes for text and semantic structure — headings, paragraphs, lists, and links. For arranging components, Vaadin’s layout components handle the most common patterns. If you are comfortable with HTML and CSS, you can also use Div with CSS flexbox or grid for more custom layouts — see Add Styling for how to apply CSS. Use Vaadin components (Button, Text Field, Grid, Dialog, and others from the component library) for interactive features like form inputs, data display, and user actions.

Tip
 For advanced DOM manipulation beyond what the HTML element classes provide, see the Element API. It lets you create any HTML element and set arbitrary attributes and properties.