> Markdown version of [Tabs](https://vaadin.com/docs/v14/ds/components/tabs). Section index: [llms.txt](https://vaadin.com/docs/v14/ds/llms.txt)

# Tabs

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

`TabsBasic.java`

```java
Tab details = new Tab("Details");
Tab payment = new Tab("Payment");
Tab shipping = new Tab("Shipping");

Tabs tabs = new Tabs(details, payment, shipping);
```

Use Tabs when you want to allow in-place navigation within a certain part of the UI, instead of showing everything at once or forcing the user to navigate between different views.

## <a id="states"></a>States

A Tab can be selected, unselected, or disabled.

`TabsStates.java`

```java
Tab selected = new Tab("Selected");

Tab unselected = new Tab("Unselected");

Tab disabled = new Tab("Disabled");
disabled.setEnabled(false);

Tabs tabs = new Tabs(selected, unselected, disabled);
tabs.setSelectedTab(selected);
```

Disable a Tab to mark it as **unavailable**. Disabled Tabs cannot be focused and may be invisible to assistive technologies like screen readers.

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

## <a id="orientation-scrolling"></a>Orientation & Scrolling

Tabs support two different orientations: horizontal (default) and vertical. Base the choice of orientation on the use case and the available space.

### <a id="horizontal"></a>Horizontal

Horizontal tabs may be easier for users to understand and associate with their contents. They are best suited for a small number of items, but provide scrolling on overflow.

`TabsHorizontal.java`

```java
Tab analytics = new Tab("Analytics");
Tab customers = new Tab("Customers");
Tab dashboards = new Tab("Dashboards");
Tab documents = new Tab("Documents");
Tab orders = new Tab("Orders");

Tabs tabs = new Tabs(analytics, customers, dashboards, documents, orders);
tabs.setMaxWidth("100%");
tabs.setWidth("400px");
```

### <a id="vertical"></a>Vertical

Vertical tabs can be a better choice for a big number of items, as it’s easier for the user to scan a vertical list of options. They may be somewhat less easy to understand and associate with their contents, however. Vertical tabs also provide scrolling on overflow.

`TabsVertical.java`

```java
Tab analytics = new Tab("Analytics");
Tab customers = new Tab("Customers");
Tab dashboards = new Tab("Dashboards");
Tab documents = new Tab("Documents");
Tab orders = new Tab("Orders");
Tab products = new Tab("Products");
Tab tasks = new Tab("Tasks");

Tabs tabs = new Tabs(
	analytics, customers, dashboards, documents, orders, products, tasks
);
tabs.setOrientation(Tabs.Orientation.VERTICAL);
tabs.setHeight("240px");
tabs.setWidth("240px");
```

### <a id="hide-scroll-buttons"></a>Hide Scroll Buttons

Horizontal Tabs display scroll buttons to aid with scrolling when their contents overflow. The buttons show that there are more tabs to either side. Hide the buttons by applying the `hide-scroll-buttons` theme variant.

`TabsHideScrollButtons.java`

```java
Tab analytics = new Tab("Analytics");
Tab customers = new Tab("Customers");
Tab dashboards = new Tab("Dashboards");
Tab documents = new Tab("Documents");
Tab orders = new Tab("Orders");
Tab products = new Tab("Products");
Tab tasks = new Tab("Tasks");

Tabs tabs = new Tabs(
	analytics, customers, dashboards, documents, orders, products, tasks
);
tabs.addThemeVariants(TabsVariant.LUMO_HIDE_SCROLL_BUTTONS);
```

> **Note:** Hiding the scroll buttons is not recommended for UIs designed to be operated on non-touchscreen devices, as horizontal scrolling can be difficult without them.

## <a id="icons-and-other-tab-content"></a>Icons and Other Tab Content

Tabs can contain more than just text.

### <a id="icons"></a>Icons

Icons can be used to make tabs more prominent and easier to identify. They can be added next to, or above the labels.

Horizontal Tabs work best with icons above the labels.

`TabsIconsHorizontal.java`

```java
Tab profile = new Tab(
	VaadinIcon.USER.create(),
	new Span("Profile")
);
Tab settings = new Tab(
	VaadinIcon.COG.create(),
	new Span("Settings")
);
Tab notifications = new Tab(
	VaadinIcon.BELL.create(),
	new Span("Notifications")
);

// Set the icon on top
for (Tab tab : new Tab[] { profile, settings, notifications }) {
	tab.addThemeVariants(TabVariant.LUMO_ICON_ON_TOP);
}

Tabs tabs = new Tabs(profile, settings, notifications);
```

Vertical Tabs work best with icons next to labels.

`TabsIconsVertical.java`

```java
Tab profile = new Tab(
	VaadinIcon.USER.create(),
	new Span("Profile")
);
Tab settings = new Tab(
	VaadinIcon.COG.create(),
	new Span("Settings")
);
Tab notifications = new Tab(
	VaadinIcon.BELL.create(),
	new Span("Notifications")
);

Tabs tabs = new Tabs(profile, settings, notifications);
tabs.setOrientation(Tabs.Orientation.VERTICAL);
```

### <a id="other-elements"></a>Other Elements

Tabs can contain virtually any UI elements, such as badges indicating the number of items per tab.

`TabsBadges.java`

```java
Tab open = new Tab(
	new Span("Open"),
	createBadge(24)
);
Tab completed = new Tab(
	new Span("Completed"),
	createBadge(439)
);
Tab cancelled = new Tab(
	new Span("Cancelled"),
	createBadge(5)
);

Tabs tabs = new Tabs(open, completed, cancelled);
```

## <a id="theme-variants"></a>Theme Variants

### <a id="centered"></a>Centered

Tabs are by default left-aligned. They can be centered using the centered theme variant.

`TabsThemeCentered.java`

```java
Tab details = new Tab("Details");
Tab payment = new Tab("Payment");
Tab shipping = new Tab("Shipping");

Tabs tabs = new Tabs(details, payment, shipping);
tabs.addThemeVariants(TabsVariant.LUMO_CENTERED);
```

**Usage recommendations**

- Visual and/or stylistic preference

- Typically used for top-level navigation

- Use with caution; default left-aligned tabs are more discoverable.

### <a id="equal-width-tabs"></a>Equal Width Tabs

Apply the `equal-width-tabs` theme variant to make each Tab share the available space. Please note that this disables the possibility for scrolling as the content never overflows.

`TabsThemeEqualWidth.java`

```java
Tab details = new Tab("Details");
Tab payment = new Tab("Payment");
Tab shipping = new Tab("Shipping");

Tabs tabs = new Tabs(details, payment, shipping);
tabs.addThemeVariants(TabsVariant.LUMO_EQUAL_WIDTH_TABS);
```

**Usage recommendations**

For a small number of tabs in a horizontally narrow space, such as:

- Tabbed sidebar

- Mobile (portrait) layouts

### <a id="minimal"></a>Minimal

Reduces visual styles to a minimum.

`TabsThemeMinimal.java`

```java
Tab details = new Tab("Details");
Tab payment = new Tab("Payment");
Tab shipping = new Tab("Shipping");

Tabs tabs = new Tabs(details, payment, shipping);
tabs.addThemeVariants(TabsVariant.LUMO_MINIMAL);
```

**Usage recommendations**

- To reduce visual clutter

- Use with caution, as this reduces the visual distinction for selected tabs to only color, which can be difficult to discern for many users.

### <a id="small"></a>Small

The `small` theme variant can be used to make the Tabs smaller.

`TabsThemeSmall.java`

```java
Tab details = new Tab("Details");
Tab payment = new Tab("Payment");
Tab shipping = new Tab("Shipping");

Tabs tabs = new Tabs(details, payment, shipping);
tabs.addThemeVariants(TabsVariant.LUMO_SMALL);
```

**Usage recommendations**

- When space is limited

## <a id="focus-and-keyboard"></a>Focus and Keyboard

Tab focus is rendered differently when focused by keyboard.

`tabs-focus-ring.ts`

```typescript
import { html, LitElement, customElement } from 'lit-element';
import '@vaadin/vaadin-tabs/vaadin-tabs';

@customElement('tabs-focus-ring')
export class Example extends LitElement {
    render() {
        return html`
      <!-- tag::snippet[] -->
      <vaadin-tabs>
        <vaadin-tab focus-ring>Details</vaadin-tab>
        <vaadin-tab>Payment</vaadin-tab>
        <vaadin-tab>Shipping</vaadin-tab>
      </vaadin-tabs>
      <!-- end::snippet[] -->
    `;
    }
}
```

Once a tab is focused, arrow keys can be used to move the focus between tabs. Press Enter or Space to select the focused tab.

## <a id="common-cases"></a>Common Cases

### <a id="switching-between-content"></a>Switching Between Content

The most common use for Tabs is to switch between different sets of content within the same view.

`TabsContent.java`

```java
details = new Tab("Details");
payment = new Tab("Payment");
shipping = new Tab("Shipping");

Tabs tabs = new Tabs(details, payment, shipping);
tabs.addSelectedChangeListener(event ->
	setContent(event.getSelectedTab())
);
```

### <a id="navigation"></a>Navigation

Tabs are often used for an application’s top-level navigation. See [App Layout](https://vaadin.com/docs/v14/ds/components/app-layout.md) for examples. Anchor elements should be used inside the tabs to provide the navigation mechanism.

## <a id="related-components"></a>Related Components

| Component                                                           | Usage recommendations                                                                                                  |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [Accordion](https://vaadin.com/docs/v14/ds/components/accordion.md) | An accordion is a vertically stacked set of expandable panels.                                                         |
| [Details](https://vaadin.com/docs/v14/ds/components/details.md)     | The Details component is an expandable panel for showing and hiding content from the user to make the UI less crowded. |

`B5247EB1-9B80-4F05-9DBB-A460481F9F4D`
