Polarity Integration Component Library

Tab Component

A tab interface consisting of three components — <pi-tab>, <pi-tab-group>, and <pi-tab-panel> — that work together to provide accessible tabbed navigation with keyboard support.

Installation

npm install @polarityio/pi-tab

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-tab';

Basic Tabs

<pi-tab-group>
  <pi-tab slot="tab" panel="general" active>General</pi-tab>
  <pi-tab slot="tab" panel="settings">Settings</pi-tab>
  <pi-tab slot="tab" panel="advanced">Advanced</pi-tab>

  <pi-tab-panel slot="panel" active>General content here.</pi-tab-panel>
  <pi-tab-panel slot="panel">Settings content here.</pi-tab-panel>
  <pi-tab-panel slot="panel">Advanced content here.</pi-tab-panel>
</pi-tab-group>

Vertical Tabs with Auto Activation

<pi-tab-group placement="start" activation="auto">
  <pi-tab slot="tab" panel="one">Tab One</pi-tab>
  <pi-tab slot="tab" panel="two">Tab Two</pi-tab>
  <pi-tab slot="tab" panel="three" disabled>Disabled</pi-tab>

  <pi-tab-panel slot="panel">Content one.</pi-tab-panel>
  <pi-tab-panel slot="panel">Content two.</pi-tab-panel>
  <pi-tab-panel slot="panel">Content three.</pi-tab-panel>
</pi-tab-group>

Scrollable Tab Panel

Add the scrollable attribute to a <pi-tab-panel> to constrain its content with a thin scrollbar and vertical resize handle. The default max-height is 300px — override it with --pi-tab-panel-max-height.

<pi-tab-group>
  <pi-tab>Logs</pi-tab>
  <pi-tab>Config</pi-tab>

  <pi-tab-panel scrollable style="--pi-tab-panel-max-height: 160px;">
    <p>2026-04-21 08:01:12 INFO — Integration started.</p>
    <p>2026-04-21 08:02:30 WARN — Slow response detected.</p>
    <!-- more content that overflows -->
  </pi-tab-panel>
  <pi-tab-panel>
    <p>Configuration content — no overflow.</p>
  </pi-tab-panel>
</pi-tab-group>

To disable the resize handle, set --pi-tab-panel-resize: none.

API Reference

<pi-tab-group>

The container component that manages tab selection, keyboard navigation, and panel visibility.

Properties

| Property | Type | Default | Description | | ------------ | --------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | placement | 'top' \| 'bottom' \| 'start' \| 'end' | 'top' | Position of tabs relative to the panels. start/end produce a vertical layout. Reflected to attribute. | | activation | 'manual' \| 'auto' | 'manual' | Tab activation mode. manual requires Enter/Space to activate; auto activates on arrow key focus. Reflected to attribute. |

Events

| Event Name | Detail | Description | | --------------- | ---------------------------------- | ----------------------------------------------------------- | | pi-tab-change | { tab: PiTab, tabIndex: number } | Fired when the active tab changes. Bubbles and is composed. |

Slots

| Slot Name | Description | | --------- | ----------------------------------- | | tab | Slot for <pi-tab> elements. | | panel | Slot for <pi-tab-panel> elements. |

CSS Parts

| Part Name | Description | | ------------ | ---------------------------------------------------- | | tab-nav | The tab navigation container (has role="tablist"). | | tab-panels | The tab panels container. |

Keyboard Navigation

| Key | Horizontal (top/bottom) | Vertical (start/end) | | ------------- | --------------------------- | ------------------------ | | Arrow Right | Focus next tab | — | | Arrow Left | Focus previous tab | — | | Arrow Down | — | Focus next tab | | Arrow Up | — | Focus previous tab | | Home | Focus first enabled tab | Focus first enabled tab | | End | Focus last enabled tab | Focus last enabled tab | | Enter / Space | Activate focused tab | Activate focused tab |

In auto activation mode, arrow keys both move focus and activate the tab. Navigation wraps around and skips disabled tabs.

<pi-tab>

An individual tab element placed inside a <pi-tab-group>.

Properties

| Property | Type | Default | Description | | ---------- | --------- | ------- | ----------------------------------------------------------------- | | active | boolean | false | Whether this tab is currently active. Reflected to attribute. | | disabled | boolean | false | Disables the tab, preventing interaction. Reflected to attribute. | | panel | string | '' | Identifier of the associated tab panel. |

Slots

| Slot Name | Description | | ------------- | ----------------------------------------------- | | prefix-icon | Icon displayed before the tab label. | | (default) | Tab label content. | | counter | Badge or counter displayed alongside the label. | | suffix-icon | Icon displayed after the tab label. |

CSS Parts

| Part Name | Description | | --------- | ------------------------------- | | tab | The main tab element container. |

<pi-tab-panel>

A content panel associated with a tab, shown when its corresponding tab is active.

Properties

| Property | Type | Default | Description | | ------------ | --------- | ------- | --------------------------------------------------------------------------------------------------------- | | active | boolean | false | Whether this panel is visible. Reflected to attribute. | | scrollable | boolean | false | Whether the panel content is scrollable with a constrained max-height, thin scrollbar, and resize handle. |

Slots

| Slot Name | Description | | ----------- | ------------------------------------ | | (default) | Panel content displayed when active. |

CSS Parts

| Part Name | Description | | --------- | ---------------------------- | | panel | The panel container element. |

CSS Custom Properties

| Property | Default | Description | | --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | | --pi-tab-panel-max-height | 300px | Maximum height of the panel content when scrollable is set. Overridable via CSS or inline style. | | --pi-tab-panel-resize | vertical | Resize behavior for the panel content (e.g., vertical, none, both). Only effective when scrollable is set. |

Accessibility

• <pi-tab> elements have role="tab" with aria-selected and aria-disabled.
• <pi-tab-group> manages role="tablist" on the navigation container.
• <pi-tab-panel> elements have role="tabpanel" with aria-hidden when inactive.
• ARIA relationships (aria-controls, aria-labelledby) are automatically linked between tabs and panels.
• Focus management follows the WAI-ARIA Tabs Pattern.

Theming

Customize the appearance using CSS custom properties. This component uses design tokens from @polarityio/pi-shared for consistent theming across the component library.

License

MIT