In-depth Guides
Angular Aria

Tabs

Overview

Tabs display layered content sections where only one panel is visible at a time. Users switch between panels by clicking tab buttons or using arrow keys to navigate the tab list.

Usage

Tabs work well for organizing related content into distinct sections where users switch between different views or categories.

Use tabs when:

  • Organizing related content into distinct sections
  • Creating settings panels with multiple categories
  • Building documentation with multiple topics
  • Implementing dashboards with different views
  • Showing content where users need to switch contexts

Avoid tabs when:

  • Building sequential forms or wizards (use a stepper pattern)
  • Navigating between pages (use router navigation)
  • Showing single content sections (no need for tabs)
  • Having more than 7-8 tabs (consider a different layout)

Features

  • Selection modes - Tabs activate automatically on focus or require manual activation
  • Keyboard navigation - Arrow keys, Home, and End for efficient tab navigation
  • Orientation - Horizontal or vertical tab list layouts
  • Lazy content - Tab panels render only when first activated
  • Disabled tabs - Disable individual tabs with focus management
  • Focus modes - Roving tabindex or activedescendant focus strategies
  • RTL support - Right-to-left language navigation

Examples

Selection follows focus

When selection follows focus, tabs activate immediately as you navigate with arrow keys. This provides instant feedback and works well for lightweight content.

Set [selectionMode]="'follow'" on the tab list to enable this behavior.

Manual activation

With manual activation, arrow keys move focus between tabs without changing the selected tab. Users press Space or Enter to activate the focused tab.

Use [selectionMode]="'explicit'" for heavy content panels to avoid unnecessary rendering.

Vertical tabs

Arrange tabs vertically for interfaces like settings panels or navigation sidebars.

Set [orientation]="'vertical'" on the tab list. Navigation changes to Up/Down arrow keys.

Lazy content rendering

Use the ngTabContent directive on an ng-template to defer rendering tab panels until they're first shown.

<div ngTabs>
  <ul ngTabList [(selectedTab)]="selectedTab">
    <li ngTab value="tab1">Tab 1</li>
    <li ngTab value="tab2">Tab 2</li>
  </ul>

  <div ngTabPanel value="tab1">
    <ng-template ngTabContent>
      <!-- This content only renders when Tab 1 is first shown -->
      <app-heavy-component />
    </ng-template>
  </div>

  <div ngTabPanel value="tab2">
    <ng-template ngTabContent>
      <!-- This content only renders when Tab 2 is first shown -->
      <app-another-component />
    </ng-template>
  </div>
</div>

By default, content remains in the DOM after the panel is hidden. Set [preserveContent]="false" to remove content when the panel is deactivated.

Disabled tabs

Disable specific tabs to prevent user interaction. Control whether disabled tabs can receive keyboard focus.

When [softDisabled]="true" on the tab list, disabled tabs can receive focus but cannot be activated. When [softDisabled]="false", disabled tabs are skipped during keyboard navigation.

Testing

Angular Aria provides component harnesses for testing tabs components. Here is an example of how to use the harnesses in a component test:

import {ComponentFixture, TestBed} from '@angular/core/testing';
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
import {ComponentHarness, HarnessLoader} from '@angular/cdk/testing';
import {TabsHarness} from '@angular/aria/tabs/testing';
import {MyTabsComponent} from './my-tabs'; // Your component

// A simple harness to help query content inside the tab panel
class TestContentHarness extends ComponentHarness {
  static hostSelector = '.test-content';
  async getText(): Promise<string> {
    return (await this.host()).text();
  }
}

describe('MyTabsComponent', () => {
  let fixture: ComponentFixture<MyTabsComponent>;
  let loader: HarnessLoader;

  beforeEach(async () => {
    TestBed.configureTestingModule({
      imports: [MyTabsComponent],
    });

    fixture = TestBed.createComponent(MyTabsComponent);
    await fixture.whenStable();
    loader = TestbedHarnessEnvironment.loader(fixture);
  });

  it('should switch tabs and scope panel queries', async () => {
    const tabs = await loader.getHarness(TabsHarness);

    // Get all tabs
    const tabItems = await tabs.getTabs();
    expect(tabItems.length).toBe(3);

    // Verify initial selection
    expect(await tabItems[0].isSelected()).toBe(true);
    expect(await tabItems[1].isSelected()).toBe(false);

    // Query content inside the active tab panel
    // TabHarness automatically scopes queries to its associated panel
    const content = await tabItems[0].getHarness(TestContentHarness);
    expect(await content.getText()).toBe('Content 1');

    // Switch to the second tab
    await tabItems[1].select();

    // Verify selection updated
    expect(await tabItems[0].isSelected()).toBe(false);
    expect(await tabItems[1].isSelected()).toBe(true);
  });
});

APIs

Tabs

The container directive that coordinates tab lists and panels.

This directive has no inputs or outputs. It serves as the root container for ngTabList, ngTab, and ngTabPanel directives.

TabList

The container for tab buttons that manages selection and keyboard navigation.

Inputs

Property Type Default Description
orientation 'horizontal' | 'vertical' 'horizontal' Tab list layout direction
wrap boolean true Whether keyboard navigation wraps from last to first tab
softDisabled boolean true When true, disabled tabs are focusable but not activatable
selectionMode 'follow' | 'explicit' 'follow' Whether tabs activate on focus or require explicit activation
focusMode 'roving' | 'activedescendant' 'roving' Focus management strategy
selectedTab any — The value of the currently selected tab (supports two-way binding)

Tab

An individual tab button.

Inputs

Property Type Default Description
value any — Required. Unique value for this tab
disabled boolean false Disables this tab

Signals

Property Type Description
selected Signal<boolean> Whether the tab is currently selected
active Signal<boolean> Whether the tab currently has focus

TabPanel

The content panel associated with a tab.

Inputs

Property Type Default Description
value any — Required. Must match the value of the associated tab
preserveContent boolean true Whether to keep panel content in DOM after deactivation

Signals

Property Type Description
visible Signal<boolean> Whether the panel is currently visible

TabContent

A structural directive for lazy rendering tab panel content.

This directive has no inputs, outputs, or methods. Apply it to an ng-template element inside a tab panel:

<div ngTabPanel value="tab1">
  <ng-template ngTabContent>
    <!-- Content here is lazily rendered -->
  </ng-template>
</div>