GitHub

Tab Layout

An ARIA tablist with active-tab state, roving keyboard navigation (Arrow / Home / End, skipping disabled tabs), badges, and a swapping panel. A Lit web component.

Stable wc import '@esa/ecology/esa-tab-layout'; Angular usage

Preview

Overview content — summary metrics and status.
Activity content — recent events log.
Settings content — configuration form.
 
<esa-tab-layout id="tabs">
  <div slot="panel-0">Overview content — summary metrics and status.</div>
  <div slot="panel-1">Activity content — recent events log.</div>
  <div slot="panel-2">Settings content — configuration form.</div>
</esa-tab-layout>

<script>
  document.getElementById('tabs').tabs = [
    { label: 'Overview' }, { label: 'Activity' }, { label: 'Settings' },
  ];
</script>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-tab-layout';

@Component({
  selector: 'app-tab-layout-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-tab-layout id="tabs" [tabs]="tabs">
      <div slot="panel-0">Overview content — summary metrics and status.</div>
      <div slot="panel-1">Activity content — recent events log.</div>
      <div slot="panel-2">Settings content — configuration form.</div>
    </esa-tab-layout>
  `,
})
export class TabLayoutDemo {
  tabs = [
    { label: 'Overview' }, { label: 'Activity' }, { label: 'Settings' },
  ];
}

Appearance

Two appearances, aligned to Beacon's UiTabsAppearance. underline (default) shows an underlined indicator on the active tab; segmented renders a segmented control — a sunken, bordered track with a filled selected segment and no indicator. (variant="pill" is the legacy alias for segmented.)

Underline appearance.
Second panel.
Third panel.
Segmented appearance.
Second panel.
Third panel.
 
<esa-tab-layout appearance="underline">…</esa-tab-layout>
<esa-tab-layout appearance="segmented">…</esa-tab-layout>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-tab-layout';

@Component({
  selector: 'app-tab-layout-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-tab-layout appearance="underline">…</esa-tab-layout>
    <esa-tab-layout appearance="segmented">…</esa-tab-layout>
  `,
})
export class TabLayoutDemo {}

Sizes

Extra small.
Two.
Small.
Two.
Medium.
Two.
Large.
Two.
 
<esa-tab-layout size="xs">…</esa-tab-layout>
<esa-tab-layout size="sm">…</esa-tab-layout>
<esa-tab-layout size="md">…</esa-tab-layout>
<esa-tab-layout size="lg">…</esa-tab-layout>
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-tab-layout';

@Component({
  selector: 'app-tab-layout-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-tab-layout size="xs">…</esa-tab-layout>
    <esa-tab-layout size="sm">…</esa-tab-layout>
    <esa-tab-layout size="md">…</esa-tab-layout>
    <esa-tab-layout size="lg">…</esa-tab-layout>
  `,
})
export class TabLayoutDemo {}

States

Tabs accept badges, and any tab can be disabled — keyboard navigation skips disabled tabs.

Inbox.
Archive (tab 2 is disabled).
 
<script>
  el.tabs = [
    { label: 'Inbox', badge: 4 },
    { label: 'Drafts', disabled: true },
    { label: 'Archive', badge: 128 },
  ];
</script>

API

PropTypeDefaultDescription
tabs EsaTab[] [] Tab definitions (property, set via JS). Each is { label; icon?; badge?; disabled? }.
active-index number 0 Index of the selected tab. Property: `activeIndex`.
size 'xs' | 'sm' | 'md' | 'lg' 'md' Tab height and type scale. Reflected as an attribute.
variant 'underline' | 'pill' 'underline' Legacy alias for appearance — pill maps to segmented. Prefer appearance.
appearance 'underline' | 'segmented' 'underline' Tab style (aligned to Beacon): underlined indicator or a segmented control on a sunken track. Reflected as an attribute.

Events

EventTypeDefaultDescription
tabchange CustomEvent — Fired when the active tab changes. detail: { index: number }. Bubbles and composed.
Binding these events from Angular

Every one of these is a CustomEvent, so the payload is on $event.detail — $event.target.value reads empty, with no error. The names are lowercase and Angular passes them to addEventListener verbatim, so camel-casing one means it never fires.

  • (tabchange)="onTabchange($event.detail)"

tabs is an array property — set it in JS, not as an attribute. Each EsaTab.icon is a raw inline SVG string.

Slots

PropTypeDefaultDescription
panel-{index} slot — Content for the matching tab; the active panel is shown. Falls back to the default slot.

The routed-tabs (RouterOutlet) branch of the Angular component is replaced here by content panels via the named slots above.

Accessibility

  • Follows the ARIA tablist pattern: role="tablist" / role="tab" / role="tabpanel" with aria-selected.
  • Roving tabindex — only the active tab is in the tab order; ArrowLeft / ArrowRight / Home / End move focus and selection, skipping disabled tabs.
  • Disabled tabs are non-interactive and excluded from keyboard traversal.

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

RoleRe-pointReach
.typography-body-md
  • --typography-body-md-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-body-md-font-size clamp(0.75rem, 0.66rem + 0.44vw, 0.9375rem) via --font-size-200
  • --typography-body-md-font-weight 350 via --typography-font-weight-regular → --font-weight-350
  • --typography-body-md-letter-spacing 0.01em via --letter-spacing-default
  • --typography-body-md-line-height 1.6 via --line-height-normal
+28 more components esa-app-shell, esa-breadcrumbs, esa-card, esa-checkbox, esa-checkbox-group, esa-collapsible, esa-combobox, esa-command-palette, esa-confirm-dialog, esa-container, esa-danger-zone, esa-dialog, esa-dropdown-menu, esa-empty-state, esa-entity-search, esa-form-field, esa-header-nav, esa-input-tag, esa-nav-dropdown, esa-page-header, esa-popover, esa-progress-bar, esa-radio-group, esa-select, esa-side-dialog, esa-snackbar-item, esa-switch-toggle, esa-textarea
.typography-microcopy-xs-strong
  • --typography-microcopy-xs-strong-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-microcopy-xs-strong-font-size clamp(0.625rem, 0.56rem + 0.32vw, 0.75rem) via --font-size-100
  • --typography-microcopy-xs-strong-font-weight 550 via --typography-font-weight-semibold → --font-weight-550
  • --typography-microcopy-xs-strong-letter-spacing 0.01em via --letter-spacing-default
  • --typography-microcopy-xs-strong-line-height 1 via --line-height-none
+5 more components esa-badge, esa-button-toggle, esa-chip-group, esa-filter-dropdown, esa-sidebar-nav

Wired to this component

No other component reads these — re-point them and esa-tab-layout is the only thing that moves.

Token Tier Resolves to
--tab-layout-height-lg component 52px
--tab-layout-height-md component 44px
--tab-layout-height-sm component 36px
--tab-layout-height-xs component 30px

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.

Token Reach Resolves to
--focus-ring-color component focus ring group · +34 more #3e9b4f via --color-border-default-focus → --color-grass-10
--focus-ring-width component focus ring group · +35 more 2px via --border-width-focus → --border-width-200
--border-width-default semantic every component 1px via --border-width-100
--color-background-brand semantic every component #46a758 via --color-grass-9
--color-background-elevation-raised semantic every component #fcfcfc via --color-gray-1
--color-background-elevation-sunken semantic every component #f0f0f0 via --color-gray-3
--color-border-default semantic every component one role per property, so a theme can move the ring's weight and its colour independently. Tier 3's --focus-ring-width now reads this instead of holding a bare 2px, which is the same shape --focus-ring-color has always had (a thin tier-3 alias over a tier-2 role) — width was simply never given the tier-2 half. * * This role was rejected once, and the rejection is worth recording because its PREMISE was wrong rather than its reasoning. The argument against an `emphasis` width was that every 2px border in the kit is micro-geometry — spinner rings, the kbd keycap lip, a chevron. The focus ring was not in that enumeration and does not fit it: 33 components render it, more than read any other tier-3 token, and it is not micro-geometry but an accessibility affordance whose weight is a legitimate brand axis (a spoke that needs a heavier ring for contrast has to be able to reach it). It is also not a `border` in any component — every consumer paints it with `outline` or `box-shadow` — which is precisely why a survey of BORDERS missed it. The name still says `border` because tier 2 already calls the ring's colour --color-border-default-focus
--color-content-default semantic every component #202020 via --color-gray-12
--color-content-default-knockout semantic every component #fcfcfc via --color-gray-1
--color-content-default-secondary semantic every component #646464 via --color-gray-11
--elevation-1 semantic every component 0 via --shadow-offset-x
--radius-md semantic every component 0.5rem via --radius-200
--radius-pill semantic every component 9999px via --radius-full
--radius-sm semantic every component 0.25rem via --radius-100
--spacing-050 primitive every component 0.125rem
--spacing-100 primitive every component 0.25rem
--spacing-150 primitive every component 0.375rem
--spacing-200 primitive every component 0.5rem
--spacing-300 primitive every component 0.75rem
--spacing-400 primitive every component 1rem
--spacing-500 primitive every component 1.5rem