Docs

Docs

RTL Support for Custom Elements

Adding right-to-left support to custom web components and styles.

Vaadin components support right-to-left (RTL) text direction out of the box. Custom elements and custom styles can respond to text direction using the native CSS :dir() pseudo-class: with the :dir(rtl) selector in styles, and with element.matches(':dir(rtl)') in JavaScript.

Note

Previously, custom elements had to extend Vaadin’s DirMixin, which synchronized the element’s dir attribute with the document-level dir attribute so that styles and JavaScript code could respond to text direction changes. The mixin is now deprecated in favor of the native :dir() selector, and it’s scheduled for removal in Vaadin 26, after which components no longer set the dir attribute on themselves.

Adjusting Styles for RTL

Review properties like padding, margin, text-align, float, and transform. For example, if your styles define directional padding:

Source code
CSS
:host {
    padding-right: 1em;
    padding-left: 2em;
}

Add an RTL override:

Source code
CSS
:host(:dir(rtl)) {
    padding-right: 2em;
    padding-left: 1em;
}

You can replace directional properties with CSS Logical Properties. Flex and Grid containers are handled well by the browser and typically don’t require adjustments.

For help adjusting styles, you can use the tools at RTLCSS. See also this comprehensive right-to-left styling guide.

Icons and Directional Symbols

If your element uses icons or Unicode symbols that indicate direction (e.g., a Back button arrow), use the appropriate icons for RTL mode.

Keyboard Navigation

If keyboard interactions use arrow keys for navigation, adjust the direction based on the text direction:

Source code
JavaScript
const dirIncrement = this.matches(':dir(rtl)') ? -1 : 1;

switch (event.key) {
    // ...
    case 'ArrowLeft':
        idx = currentIdx - dirIncrement;
        break;
    case 'ArrowRight':
        idx = currentIdx + dirIncrement;
        break;
    // ...
}

Custom elements that rely on JavaScript calculations for sizing, position, or horizontal scroll may also need adjustments for RTL.

If you have visual tests, consider adding or updating them to run in RTL mode as well.

Frontend-Only RTL

For frontend-only applications, set document.dir = 'rtl' to enable right-to-left mode.

Updated –