Documentation

Documentation

Tabs

Source: TypeScript / Java
Tabs are used to organize and group content into sections that the user can navigate.

Tabs are used to organize and group content into sections that the user can navigate.

Below is a simple example of tabs with labels:

Open in a
new tab
<vaadin-tabs>
  <vaadin-tab>Details</vaadin-tab>
  <vaadin-tab>Payment</vaadin-tab>
  <vaadin-tab>Shipping</vaadin-tab>
</vaadin-tabs>

Use Tabs when you want to allow in-place navigation within a certain part of the UI — that is to say, without having to load another page and instead of showing everything at once, or forcing the user to navigate to different views.

Tab Sheet

Tabs are most conveniently used as part of a Tab Sheet that includes automatically switched content areas for each tab. Try clicking on the tabs in the example below. Notice how different text is displayed for each tab.

Open in a
new tab
<vaadin-tabsheet>
  <vaadin-tabs slot="tabs">
    <vaadin-tab id="dashboard-tab">Dashboard</vaadin-tab>
    <vaadin-tab id="payment-tab">Payment</vaadin-tab>
    <vaadin-tab id="shipping-tab">Shipping</vaadin-tab>
  </vaadin-tabs>

  <div tab="dashboard-tab">This is the Dashboard tab content</div>
  <div tab="payment-tab">This is the Payment tab content</div>
  <div tab="shipping-tab">This is the Shipping tab content</div>
</vaadin-tabsheet>

States

A Tab can be selected, unselected, or disabled.

Open in a
new tab
<vaadin-tabs>
  <vaadin-tab>Selected</vaadin-tab>
  <vaadin-tab>Unselected</vaadin-tab>
  <vaadin-tab disabled>Disabled</vaadin-tab>
</vaadin-tabs>

You can disable a tab to mark it as unavailable. Disabled tabs can’t be focused and may be invisible to assistive technologies, such as screen readers.

Disabling can be preferable to hiding an element to prevent changes in layout when the element’s visibility changes. They can also make users aware of its existence even when unavailable.

Autoselect (Java Only)

The first tab you add to Tabs or Tab Sheet is automatically selected. Similarly, when a selected tab is removed, the next available tab is automatically selected.

Autoselect is enabled by default, but you can disable this behavior if needed. Notice how none of the tabs in the example below are initially selected.

Open in a
new tab
Tabs tabs = new Tabs();
tabs.setAutoselect(false);

When using autoselect and tab selection change listeners, you should add selection change listeners before adding any tabs if you want the listeners to trigger for the automatically selected tab.

Orientation & Overflow

Tabs support two different orientations: horizontal (default) and vertical, which is not currently supported in Tab Sheets. Base your choice of orientation on your particular use case and the available space. Both are explained below.

Horizontal

Horizontal tabs may be easier for users to understand and associate with the content. They’re best suited for a small number of items, but provide scrolling on overflow. Try scrolling horizontally the tabs in the example here: you’ll see that there are more than the initially visible ones.

Open in a
new tab
<vaadin-tabs style="max-width: 100%; width: 400px;">
  <vaadin-tab>Analytics</vaadin-tab>
  <vaadin-tab>Customers</vaadin-tab>
  <vaadin-tab>Dashboards</vaadin-tab>
  <vaadin-tab>Documents</vaadin-tab>
  <vaadin-tab>Orders</vaadin-tab>
</vaadin-tabs>

In horizontal orientation, scroll buttons are displayed by default to aid scrolling the tabs. These can be disabled by applying the hide-scroll-buttons theme variant. Notice in the example below that there’s no scrollbar or scroll buttons, but you can still scroll to reveal the overflowing tabs.

Open in a
new tab
<vaadin-tabs theme="hide-scroll-buttons" style="max-width: 100%; width: 400px;">
  <vaadin-tab>Analytics</vaadin-tab>
  <vaadin-tab>Customers</vaadin-tab>
  <vaadin-tab>Dashboards</vaadin-tab>
  <vaadin-tab>Documents</vaadin-tab>
  <vaadin-tab>Orders</vaadin-tab>
  <vaadin-tab>Products</vaadin-tab>
  <vaadin-tab>Tasks</vaadin-tab>
</vaadin-tabs>
Note

Hiding the scroll buttons isn’t recommended, though, for UIs designed to be operated on non-touchscreen devices, as horizontal scrolling can be difficult without them.

Vertical

Vertical tabs can sometimes be a better choice for a large number of items. It’s easier for the user to scan a vertical list of options. However, they may not always be easy to understand and associate with the content.

Vertical tabs also provide scrolling on overflow, but no scroll buttons. Incidentally, vertical orientation is not available for Tab Sheets.

Open in a
new tab
<vaadin-tabs orientation="vertical" style="height: 240px; width: 240px;">
  <vaadin-tab>Analytics</vaadin-tab>
  <vaadin-tab>Customers</vaadin-tab>
  <vaadin-tab>Dashboards</vaadin-tab>
  <vaadin-tab>Documents</vaadin-tab>
  <vaadin-tab>Orders</vaadin-tab>
  <vaadin-tab>Products</vaadin-tab>
  <vaadin-tab>Tasks</vaadin-tab>
</vaadin-tabs>

Icons & Other Tab Content

In addition to text, tabs can contain icons and other content.

Icons

Icons can be used to make tabs more prominent and easier to identify. They can be added next to the labels or above them. Generally, horizontal tabs work best with icons above the labels, as you can see in the example below.

Open in a
new tab
<vaadin-tabs>
  <vaadin-tab theme="icon-on-top">
    <vaadin-icon icon="vaadin:user"></vaadin-icon>
    <span>Profile</span>
  </vaadin-tab>
  <vaadin-tab theme="icon-on-top">
    <vaadin-icon icon="vaadin:cog"></vaadin-icon>
    <span>Settings</span>
  </vaadin-tab>
  <vaadin-tab theme="icon-on-top">
    <vaadin-icon icon="vaadin:bell"></vaadin-icon>
    <span>Notifications</span>
  </vaadin-tab>
</vaadin-tabs>

Vertical tabs work best with icons next to labels, as you can see here.

Open in a
new tab
<vaadin-tabs orientation="vertical">
  <vaadin-tab>
    <vaadin-icon icon="vaadin:user"></vaadin-icon>
    <span>Profile</span>
  </vaadin-tab>
  <vaadin-tab>
    <vaadin-icon icon="vaadin:cog"></vaadin-icon>
    <span>Settings</span>
  </vaadin-tab>
  <vaadin-tab>
    <vaadin-icon icon="vaadin:bell"></vaadin-icon>
    <span>Notifications</span>
  </vaadin-tab>
</vaadin-tabs>

Icon-only labels may sometimes be appealing, but they should provide a textual description using a Tooltip, or an aria-label attribute for assistive technologies.

Other Elements

Tabs can contain almost any UI elements. For instance, they can contain badges indicating the number of items per tab. In this example, there’s a gray box with a number to the right of each tab label, indicating the count for each.

Open in a
new tab
<!--
  NOTE: You need import the 'lumo-badge' style sheets to use theme="badge"
-->
<vaadin-tabs>
  <vaadin-tab>
    <span>Open</span>
    <span theme="badge small contrast">24</span>
  </vaadin-tab>
  <vaadin-tab>
    <span>Completed</span>
    <span theme="badge small contrast">439</span>
  </vaadin-tab>
  <vaadin-tab>
    <span>Cancelled</span>
    <span theme="badge small contrast">5</span>
  </vaadin-tab>
</vaadin-tabs>

Theme Variants

The following theme variants are available for Tabs and Tab Sheet.

Centered

By default, tabs are left-aligned. They can be centered using the centered theme variant.

Open in a
new tab
<vaadin-tabs theme="centered">
  <vaadin-tab>Details</vaadin-tab>
  <vaadin-tab>Payment</vaadin-tab>
  <vaadin-tab>Shipping</vaadin-tab>
</vaadin-tabs>

You can use this variant to suit your visual and stylistic preference. It’s typically used for top-level navigation. However, use it only where appropriate since by default left-aligned tabs are more discoverable and what most users expect.

Equal-Width Tabs

Apply the equal-width-tabs theme variant to make each tab share equally the available space. This disables the ability to scroll, though, since the content never overflows.

Open in a
new tab
<vaadin-tabs theme="equal-width-tabs">
  <vaadin-tab>Details</vaadin-tab>
  <vaadin-tab>Payment</vaadin-tab>
  <vaadin-tab>Shipping</vaadin-tab>
</vaadin-tabs>

Use this variant when there are a small number of tabs in a narrow space, such as for a tabbed sidebar and for mobile (i.e., portrait) layouts.

Minimal

The minimal theme variant reduces visual styles to a minimum.

Open in a
new tab
<vaadin-tabs theme="minimal">
  <vaadin-tab>Details</vaadin-tab>
  <vaadin-tab>Payment</vaadin-tab>
  <vaadin-tab>Shipping</vaadin-tab>
</vaadin-tabs>

You can generally use this to reduce visual clutter. However, use it with caution as it reduces the visual distinction of selected tabs to color only. This can be difficult to discern for many users.

Small

The small theme variant can be used to make the Tabs smaller. This can be good when space is limited. Compare the tabs here to previous ones. You can see these are slightly smaller.

Open in a
new tab
<vaadin-tabs theme="small">
  <vaadin-tab>Details</vaadin-tab>
  <vaadin-tab>Payment</vaadin-tab>
  <vaadin-tab>Shipping</vaadin-tab>
</vaadin-tabs>

Bordered

The bordered theme variant adds a border around the Tab Sheet component.

Open in a
new tab
<vaadin-tabsheet theme="bordered">
  <vaadin-tabs slot="tabs">
    <vaadin-tab id="dashboard-tab">Dashboard</vaadin-tab>
    <vaadin-tab id="payment-tab">Payment</vaadin-tab>
    <vaadin-tab id="shipping-tab">Shipping</vaadin-tab>
  </vaadin-tabs>

  <div tab="dashboard-tab">This is the Dashboard tab content</div>
  <div tab="payment-tab">This is the Payment tab content</div>
  <div tab="shipping-tab">This is the Shipping tab content</div>
</vaadin-tabsheet>

Prefix & Suffix

Custom content can be placed before or after the tabs in a Tab Sheet by placing that content in the prefix and suffix slots. Notice the additional content at both ends of the tab bar in this example.

Open in a
new tab
<vaadin-button slot="prefix">Close all</vaadin-button>

<vaadin-button slot="suffix" theme="icon" aria-label="Add tab">
  <vaadin-icon icon="vaadin:plus"></vaadin-icon>
</vaadin-button>

Focus & Keyboard

Tab focus is rendered differently when focused by the keyboard. Once a tab is focused, arrow keys can be used to move the focus between tabs. Try pressing Enter or Space to select the tab on which to focus — or click on one tab with your mouse. Then use the left and right arrow keys to shift the focus.

Open in a
new tab
<vaadin-tabs>
  <vaadin-tab focus-ring>Details</vaadin-tab>
  <vaadin-tab>Payment</vaadin-tab>
  <vaadin-tab>Shipping</vaadin-tab>
</vaadin-tabs>

Common Cases

Content Switching without Tab Sheet

Using the integrated content areas in Tab Sheet is the easiest way to switch among the different content for each tab. Sometimes, such as when the tabs need to be separated structurally from their content areas, it may be necessary to use the stand-alone Tabs component and manually implement content switching.

Try clicking on each tab here. Notice how the text content changes depending on which you select.

Open in a
new tab
<vaadin-tabs @selected-changed="${this.selectedChanged}">
  <vaadin-tab>Dashboard</vaadin-tab>
  <vaadin-tab>Payment</vaadin-tab>
  <vaadin-tab>Shipping</vaadin-tab>
</vaadin-tabs>

<vaadin-vertical-layout theme="padding">
  <p>${this.content}</p>
</vaadin-vertical-layout>

Lazy Initialization of Tab Contents

Sometimes it can be desirable to initialize the contents for a tab, lazily. That is to say, delay its initialization until the tab is selected. When you first click on one of the tabs below, you’ll notice a loading indicator, and a short delay until the tab content is displayed for each.

Open in a
new tab
@state()
private accessor visitedTabs = new Set<number>();

private selectedTabChanged(event: TabSheetSelectedChangedEvent) {
  this.visitedTabs = new Set([...this.visitedTabs, event.detail.value]);
}

protected override render() {
  return html`
    <vaadin-tabsheet @selected-changed=${this.selectedTabChanged}>
      <vaadin-tabs slot="tabs">
        <vaadin-tab id="dashboard-tab">Dashboard</vaadin-tab>
        <vaadin-tab id="payment-tab">Payment</vaadin-tab>
        <vaadin-tab id="shipping-tab">Shipping</vaadin-tab>
      </vaadin-tabs>

      ${this.visitedTabs.has(0)
        ? html`<div tab="dashboard-tab">This is the Dashboard tab content</div>`
        : ''}
      ${this.visitedTabs.has(1)
        ? html`<div tab="payment-tab">This is the Payment tab content</div>`
        : ''}
      ${this.visitedTabs.has(2)
        ? html`<div tab="shipping-tab">This is the Shipping tab content</div>`
        : ''}
    </vaadin-tabsheet>
  `;
}
Component Usage recommendations

Accordion

An accordion is a vertically stacked set of expandable panels.

Details

The Details component is an expandable panel for showing and hiding content to make the UI less crowded.

D66CE920-3532-41D6-9EB3-C2B91F77CC40