Tabs

When to use

Use tabs to let someone switch between a few different views of related content that all live on the same page, without navigating away. This very page's own Overview, API, Examples, and Accessibility split is a tabs component. For a sequence of steps someone has to complete in order, such as a checkout or a multi-step form, a stepper fits better than tabs.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/tabs.js";

<eun-tab-group>
  <eun-tab slot="navigation" panel="overview">Overview</eun-tab>
  <eun-tab slot="navigation" panel="details">Details</eun-tab>

  <eun-tab-panel name="overview">Overview content.</eun-tab-panel>
  <eun-tab-panel name="details">Details content.</eun-tab-panel>
</eun-tab-group>

npm install @eunomia/elements

import "@eunomia/elements/tabs.js";

function Settings() {
  return (
    <eun-tab-group>
      <eun-tab slot="navigation" panel="overview">
        Overview
      </eun-tab>
      <eun-tab slot="navigation" panel="details">
        Details
      </eun-tab>

      <eun-tab-panel name="overview">Overview content.</eun-tab-panel>
      <eun-tab-panel name="details">Details content.</eun-tab-panel>
    </eun-tab-group>
  );
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/tabs.js";
</script>

<template>
  <eun-tab-group>
    <eun-tab slot="navigation" panel="overview">Overview</eun-tab>
    <eun-tab slot="navigation" panel="details">Details</eun-tab>

    <eun-tab-panel name="overview">Overview content.</eun-tab-panel>
    <eun-tab-panel name="details">Details content.</eun-tab-panel>
  </eun-tab-group>
</template>

Alternatives

Guidance

Live testing

Properties

Layout and display

Alignment

align on eun-tab-group positions the tab headers: start (default), center, or end.

start (default)

<eun-tab-group> ... </eun-tab-group>

center

<eun-tab-group align="center"> ... </eun-tab-group>

end

<eun-tab-group align="end"> ... </eun-tab-group>

Full width

Set full to stretch the tab header to 100% of the group's width. The width is divided equally between the tabs, and each label is centered in its share. It makes align irrelevant, since nothing is left to align. A tab whose label doesn't fit its share keeps the room it needs, and the header scrolls like in "Overflow scrolling" below once the labels no longer fit.

<eun-tab-group full> ... </eun-tab-group>

Filling the height

Set fill when the group has a height of its own, such as a grid row or a fixed height, and the active panel should take all the room left under the tab header. Give the panel overflow: auto so its content scrolls inside it while the tabs stay in place.

<eun-tab-group fill style="height: 100%;">
  ...
  <eun-tab-panel name="a" style="overflow: auto;"> ... </eun-tab-panel>
</eun-tab-group>

Overflow scrolling

When the tab headers are wider than the available space, the header row becomes horizontally scrollable and left/right arrows appear to scroll it, rather than wrapping or shrinking the tabs. This is especially common on mobile viewports.

<eun-tab-group style="max-width: 320px; --tab-arrows-color: #f4f4f2;">
  ...
</eun-tab-group>

--tab-arrows-color defaults to --eun-color-grey-0 (plain white), which only blends in on a white surface. Set it to whatever background the tabs actually sit on, such as this page's own demo-block background, so the gradient fades into it instead of leaving a visible seam.

The demo above is capped at 320px to reproduce a mobile-width overflow regardless of your actual viewport. The same behavior kicks in on any real viewport once the tabs no longer fit.

Hiding the indicator

Set the boolean hideIndicator on eun-tab-group to remove the moving underline beneath the active tab.

<eun-tab-group hide-indicator> ... </eun-tab-group>

Behavior

Animation

animation controls the panel-switch transition for a click or keyboard activation: slide (default), fade, or none. Click between the tabs below to compare. A touch swipe is never affected by this setting, so see Touch swipe below.

slide (default)

fade

none

<eun-tab-group animation="fade"> ... </eun-tab-group>
<eun-tab-group animation="none"> ... </eun-tab-group>

Touch swipe

On a touch device, dragging horizontally anywhere over the active panel pages to the next/previous tab. The panel and its incoming neighbor track the finger 1:1 the whole way, not just a jump once the gesture ends, and release past the swipe threshold to commit or short of it to spring back, easing the short remaining distance into place either way. That settle is a plain position transition, not animation (see Animation above), which never applies to a swipe, only to a click or keyboard change. This works out of the box, with nothing to configure. Try it on the demo below with a touchscreen or your browser's device emulation.

Disabled tabs are skipped, same as ArrowLeft/ArrowRight, and dragging past the first/last enabled tab meets resistance instead of doing nothing. See the mobile swipe test page for a full-width harness to try this on an actual phone.

Content

Icons and badges

A eun-tab accepts an icon attribute (a Eunomia icon name) or a custom icon in the icon slot, plus a boolean badge to show a notification dot.

import "@eunomia/elements/icon.js";

<eun-tab slot="navigation" panel="inbox" icon="mail" badge> Inbox </eun-tab>

The icon module must be imported alongside the tabs for the icon to render.

Numeric badge

For a real count instead of a plain dot, slot a eun-badge into the tab's own badge slot. It lands in the exact same spot the boolean dot above occupies, and takes priority over it if both are somehow set at once.

import "@eunomia/elements/icon.js";
import "@eunomia/elements/badge.js";

<eun-tab slot="navigation" panel="inbox" icon="mail">
  Inbox
  <eun-badge slot="badge">5</eun-badge>
</eun-tab>

Disabled tab

A disabled tab can't be activated, by click or keyboard, and is skipped when navigating with arrow keys.

<eun-tab slot="navigation" panel="b" disabled>Disabled</eun-tab>

Set --tab-disabled-display: none; to hide a disabled tab entirely instead of showing it dimmed out, for cases where a permission or feature-flag check should remove the option rather than just block it.

<eun-tab
  slot="navigation"
  panel="b"
  disabled
  style="--tab-disabled-display: none;"
  >Hidden</eun-tab
>

Server-side rendering

Before the tab group upgrades, every panel shows one under the other, then all but one disappear. Link tabs-ssr.css in the page's <head> to show the tab list and the active panel only, from the first paint:

<link
  rel="stylesheet"
  href="node_modules/@eunomia/elements/dist/ssr/tabs-ssr.css"
/>

A bundler that resolves package exports can reach it as @eunomia/elements/tabs-ssr.css.

The active panel is the one at the same position as the tab marked active, or the first one, so keep the panels in the same order as the tabs (up to 12). It covers align, full, hide-indicator, disabled tabs and the --tab-* spacing and color properties. Tab icons appear with the upgrade, and a tab list too long for its width wraps until then instead of scrolling.

Theming

Every color and spacing value is exposed as a CSS custom property on eun-tab-group and eun-tab (full list in the API tab), so the tabs repaint with the active theme automatically. See Theming.

<eun-tab-group
  style="--tab-indicator-color: #b45309; --tab-active-text-color: #b45309;"
>
  ...
</eun-tab-group>

The custom properties that change colors, borders, shadows and corners, at a glance. The API tab lists every property of the component.

Keyboard and focus

Keyboard interactions

When focus is on a tab:

Disabled tabs are skipped entirely when navigating with arrow keys.

Focus management

Only the active tab is in the tab order (tabindex="0"). Inactive tabs are reachable with arrow keys but skipped by Tab, matching the standard ARIA tabs pattern. eun-tab-panel also gets tabindex="0" by default, so a panel whose content has no focusable element of its own (plain text, an image, ...) is still reachable by keyboard right after its tab. It then draws its own focus ring, set with --tab-panel-focus-outline.

The eun-tab host is the element that takes focus, but its ring is drawn on the tab by the component itself and the host's own outline is forced to none. A global *:focus-visible rule on the page therefore never adds a second ring around a tab.

Touch swipe

Dragging left/right anywhere over the active panel is only recognized as a swipe once the drag is more horizontal than vertical, so a vertical drag still scrolls the page normally. It activates the same next/previous tab ArrowRight/ArrowLeft would, tracking the finger live rather than only reacting once the gesture ends, then easing the short remaining distance into place on release (committing, or springing back). It's purely an additive touch convenience: every tab stays present and independently reachable regardless of pointer type, and click/keyboard activation are unchanged. Disabled tabs are skipped, same as arrow-key navigation.

Semantics and screen readers

Aria roles

eun-tab-group exposes role="tablist" on its header row, eun-tab sets role="tab" with aria-selected and aria-controls kept in sync with the active state, and eun-tab-panel sets role="tabpanel" with aria-labelledby pointing back at its tab, all wired up automatically from the panel / name pairing, with nothing to set by hand.

Labeling the tablist

When a page has more than one tab group, or the group's purpose isn't already obvious from a preceding heading, give it an accessible name so screen reader users can tell tab groups apart:

<eun-tab-group aria-label="Account settings"> ... </eun-tab-group>

aria-label set on <eun-tab-group> is forwarded to the internal role="tablist" element. It isn't visible, only announced.

Disabled tabs

A disabled eun-tab gets aria-disabled="true" in addition to being skipped by arrow-key navigation, so assistive technology announces its unavailable state instead of only relying on the dimmed style. --tab-disabled-display: none; (see the Examples tab) removes it visually and from the tab order entirely, rather than announcing it as unavailable, for cases like a permission check where the option shouldn't appear to exist at all.

Reduced motion

The panel-switch animation (slide / fade), the moving active-tab / hover indicators, and a touch swipe's own release-settling transition all respect prefers-reduced-motion: reduce: with that OS-level setting on, every transition and animation is disabled regardless of the animation attribute, so a click/keyboard panel switch, and a swipe's release, happen instantly instead of easing. A swipe's live 1:1 tracking while the finger is still moving is unaffected either way, since that's direct manipulation rather than a decorative animation. See Touch swipe above.