Documentation versions (currently viewingVaadin 23)

You are viewing documentation for Vaadin 23. View latest documentation

Site Customization

The documentation website styles can be customized to fit the brand and design guidelines of your organization. A custom application theme can also be applied, which affects the theme of rendered UI examples within the documentation pages.

Website Styles

The website’s styles can be defined in the global.css style sheet in the dspublisher/docs-theme folder. Most styles can be customized using custom properties.

The following are the most commonly used style properties:


Font family


Font family for headings


Font size for H1…​H6 level headings


Color of body text


Color of headings


Color of unvisited links


Color of visited links


Header background color


Selected tab color (for code sample tabs, etc)


Max width of the website’s content


Width of the page sidebar / table of contents


Max width of the page’s body (excluding sidebar/table of contents)

The following properties are set in an HTML selector block:

html {
  --docs-header-background-color: green;
  --docs-font-family: 'Times New Roman';

Changes to the website’s styles are automatically applied after a couple of seconds.

The “full name” given to the initialization script sets the website’s title. See Settings for changing it after initialization.

The title text size is determined by the --docs-font-size-h3 property, but its styling can be fully customized as follows:

header h3 {
  --docs-heading-text-color: red;
  --docs-font-family-heading: Helvetica;

A logo image can be inserted into website’s header by copying the image into the docs-theme folder and replacing the background-image value in the header style block.

Depending on the size and proportions of the image, you may also need to set the background-size and background-repeat properties as follows:

header h3 a::before {
  background-image: url("logo.png");
  background-size: contain;
  background-repeat: no-repeat;
Application theme
This section is about styling the documentation website itself. See Applying a Custom Application Theme for instructions on how to apply a theme which is used in UI examples.

Custom Top Header

You can use the empty top-level header element (<dspublisher-header>) on the documentation site, above the application header, to add custom content inside it using the "[filename]dspublisher/docs-theme/header.ts`" file. If it exports a custom element class, Design System Publisher uses it to register a new custom element with the tag name `dspublisher-header, which gets rendered as the top header.

import { html, LitElement } from 'lit-element';

export default class extends LitElement {
  render() {
    return html`
      <div>This is my custom header</div>

Since the top-level header is a custom element which gets dynamically defined, it may cause a layout shift when this happens. If you know the height of the custom header in advance, you can avoid the layout shift by assigning a static height for the <dspublisher-header> element in the global.css styles.

dspublisher-header {
  height: 100px;


Various aspects of the website can be configured through environment variables in the dspublisher/.env file:


The website’s page title, which appears in the browser’s chrome. This title is also used in web search results (Google, etc) and in social share previews. Doesn’t appear anywhere in the documentation website UI.


Path to the site theme folder


Path to the root folder for articles. Relative path to the project root folder.


Boolean that determines whether to load the custom top header content in development mode


Boolean that determines whether all frontend resources are loaded up-front when the first component sample is encountered. See details below.


Required, if the application isn’t deployed on the root path “/”. Only effective when building for production.

If you only intend to provide TypeScript component examples, you can optimize the loading of frontend resources by setting DOCS_IMPORT_EXAMPLE_RESOURCES to false. It disables the automatic loading of any frontend resources needed for Java samples.

The website needs to be rebuilt, or restarted in development mode, in order for changes to these environment variables to take effect.