Styling Components

You should be familiar with Style Scopes, CSS Custom Properties, and Importing Style Sheets before you can style Vaadin components effectively.

Vaadin components use the ThemableMixin utility, which allows developers to add custom style sheets to the component’s local scope. Your custom components can also utilize the same mixin. This documentation applies only to such components.

As an example, we customize the styles of the text field component.

You might need to use more specific selectors to override the current theme’s styles. Use the browser inspector to identify the applied styles for the element that you wish to customize.

See Importing Style Sheets for instructions how to import the above styles into the local style scope of the text field component.

Currently, the only global CSS that can affect styles inside a shadow DOM’s local scope are properties that are inherited. Properties can be inherited by default, such as font-family, color and all custom properties, or explicitly by the custom element using the inherit property value.

You can adjust any component-specific custom properties in the global scope, making them affect all instances of the component.

You can find component-specific custom properties from the component’s HTML API documentation. For example, see the Styling section for Text Field.

Most components do not have any specific custom properties. Instead, themes provide most of the custom properties that you can customize. See Lumo and Material for the documentation of those properties.

Vaadin components define certain elements inside their shadow DOM as their stylable parts. They form the public theming and styling API of the component, together with custom properties and state attributes. These stylable elements are marked with the part attribute.

The internal parts of each component are listed in the component’s HTML API documentation. See the Styling section in Text Field API docs for an example.

When writing style sheets for a component’s local style scope (inside shadow DOM), a subset of CSS selectors is considered as part of a component’s public styling API. Other selectors (including the .class and #id selectors) may stop working with any release because they are considered as internal implementation details.

In general, the [part] attribute selector is the only one you should use to target elements inside a component.

Do not rely on the element type which a part applies to. For example, given <input type="text" part="value">, you should not rely on the information that the element is actually a native <input> element, for example by using a selector like input[part="value"]. This is considered as an internal implementation detail. The element type could change in the future while the part name stays the same, for example, to <div contenteditable="true" part="value">.

Some components expose their internal state as top-level attributes for styling purposes.

For example, we can style the text field component when it is invalid, using the [invalid] state attribute selector.

The state attributes for each component are listed in the component’s HTML API documentation. See the Styling section in Text Field API docs for an example.

In addition to the [state] attributes, standard CSS pseudo-classes (:hover, :active, etc.) can be used for both the component host and stylable parts.

Like the host element, named internal parts can also expose state attributes for themselves, which can be used for styling. These are also listed in the element’s API documentation.

For example, you can target a selected date in a <vaadin-date-picker>:

Components can contain other components inside their shadow DOM. This creates a hierarchy of style scopes.

The customizations we did for the text field component end up affecting other components as well, which internally use text field. For example, Combo Box, Date Picker, Time Picker and Select all contain a text field, and those components will automatically "inherit" our style customizations.

In some cases it is undesirable to style all component instances and affect sub-components across multiple parent components. Sometimes you only want to target the text field inside a single Combo Box.

Theme variants (the theme attribute values) are propagated from the parent component to all of its sub-components. They allow you to scope sub-component styles per-instance.

Theme variant propagation is not limited to the built-in variants (theme attribute values). Your custom theme variants will propagate in the same way.

Components such as Dialog, Notification, Combo Box, Date Picker, Time Picker, Select, Menu Bar and Context Menu internally use the Overlay component (<vaadin-overlay>).

The Overlay component allows the main components to render content on top of all other components in the application. It avoids any potential clipping stacking context issues where the overlay would be partially or completely hidden depending on where it is placed in the component hierarchy. One example of a such situation are Grid cells, which create a clipping stacking context.

All components that have an overlay sub-component have their own extension of the base Overlay component, for example “Dialog Overlay” (<vaadin-dialog-overlay>) and “Date Picker Overlay” (<vaadin-date-picker-overlay>). As an overlay is considered as a sub-component of the main component, sub-component variants apply to them as well.

See Sub-components for the component hierarchy reference.

In some cases the parent component can be completely hidden, as in the dialog component for example, whereas sometimes both the parent component and its overlay component can contain content, as for example in the date picker component.

A style sheet imported into a component’s local scope (see Importing Style Sheets and Style Scopes) affects all the instances of the component. But what if you only want to target a single instance of a component with custom styles?

There are two ways to scope styles to specific component instances:

You can also use the theme attribute (see custom component variants) as a scoping selector for your style overrides, as shown in the example below. The theme attribute has the benefit of propagating through the sub-components (other attributes do not propagate).

12B5A21A-9B84-476A-98F2-EA8F31C670F4