GUILD OF GLEKS UIv21.19.0

gog-tabs / gog-tab

Tabs

A tablist over projected <gog-tab> children. Each tab declares its own header text, icon and disabled state, so a tab is defined in exactly one place rather than split between a header array and a content block.

Overview

Import both components and nest them.

typescript
import { TabComponent, TabsComponent } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [TabsComponent, TabComponent],
})

activeIndex is two-way and gogTabChange reports each change. A disabled tab is skipped by the arrow keys and cannot be chosen.

Profile content.

activeIndex: 0 · gogTabChange: none yet

<gog-tabs ariaLabel="Account" [(activeIndex)]="activeIndex" (gogTabChange)="lastChange.set($event)">
  <gog-tab label="Profile"><p>Profile content.</p></gog-tab>
  <gog-tab label="Billing"><p>Billing content.</p></gog-tab>
  <gog-tab label="Audit" disabled><p>Not available.</p></gog-tab>
  <gog-tab label="Team"><p>Team content.</p></gog-tab>
</gog-tabs>

<p>activeIndex: {{ activeIndex() }} · gogTabChange: {{ lastChange() ?? 'none yet' }}</p>

Examples

Sizes and tab states

A tab is active, inactive or disabled; every tablist here holds one of each. A tab is disabled through its own disabled input. Hover, focus and press are pseudo-class states a page cannot force; the headers are live.

size: xsm

Profile.

size: sm

Profile.

size: md

Profile.

size: lg

Profile.

size: slg

Profile.

<!-- Each tablist holds an active tab, an inactive one and a disabled one. -->
@for (size of sizes; track size) {
  <p>size: {{ size }}</p>
  <gog-tabs [size]="size" ariaLabel="Account">
    <gog-tab label="Profile"><p>Profile.</p></gog-tab>
    <gog-tab label="Billing"><p>Billing.</p></gog-tab>
    <gog-tab label="Audit" disabled><p>Audit.</p></gog-tab>
  </gog-tabs>
}

Alignment

Where the headers sit in the row. stretch shares the row between them; the other three keep each header its natural width.

align: start

Profile.

align: center

Profile.

align: end

Profile.

align: stretch

Profile.

@for (align of aligns; track align) {
  <p>align: {{ align }}</p>
  <gog-tabs [align]="align" size="sm" ariaLabel="Account">
    <gog-tab label="Profile"><p>Profile.</p></gog-tab>
    <gog-tab label="Billing"><p>Billing.</p></gog-tab>
    <gog-tab label="Audit" disabled><p>Audit.</p></gog-tab>
  </gog-tabs>
}

Icons

iconName on a gog-tab adds a leading icon to the default header. It is aria-hidden: the label names the tab.

Inbox.

<gog-tabs ariaLabel="Mailbox">
  <gog-tab label="Inbox" iconName="mail"><p>Inbox.</p></gog-tab>
  <gog-tab label="Starred" iconName="star"><p>Starred.</p></gog-tab>
  <gog-tab label="Archive" iconName="download"><p>Archive.</p></gog-tab>
</gog-tabs>

Custom headers

A gogTabHeader template replaces every header button's content, with the gog-tab itself as $implicit and active, disabled and index beside it. It renders inside the tab's button, so it must not hold another control.

Twelve unread.

<gog-tabs ariaLabel="Mailbox">
  <!-- One template for every header. It renders inside the tab's button: markup only. -->
  <ng-template gogTabHeader let-tab let-active="active">
    {{ tab.label() }}
    @if (tab.label() === 'Inbox') {
      <gog-tag size="xsm" [variant]="active ? 'info' : 'warning'">12</gog-tag>
    }
  </ng-template>
  <gog-tab label="Inbox"><p>Twelve unread.</p></gog-tab>
  <gog-tab label="Sent"><p>Sent.</p></gog-tab>
</gog-tabs>

Vertical

The headers stack beside the panel, and ArrowUp / ArrowDown move between them instead of left and right.

General settings.

<gog-tabs orientation="vertical" ariaLabel="Settings">
  <gog-tab label="General"><p>General settings.</p></gog-tab>
  <gog-tab label="Security"><p>Security settings.</p></gog-tab>
  <gog-tab label="Billing"><p>Billing settings.</p></gog-tab>
</gog-tabs>

Overflowing headers

Headers that do not fit scroll inside a gog-scroll rather than a native scrollbar — the one piece of chrome no --gog-* token can reach. With scrollActiveIntoView on (the default) choosing a tab centres it — instantly on first render and under prefers-reduced-motion, smoothly otherwise — and the track is hidden. The second row turns it off and gets a track, since then it is the only hint there is more to reach; showScrollTrack sets the track explicitly.

September.

January.

<!-- scrollActiveIntoView on (the default): the chosen tab is centred, no track. -->
<gog-tabs size="sm" ariaLabel="Month" [activeIndex]="8">
  @for (month of months; track month) {
    <gog-tab [label]="month">
      <p>{{ month }}.</p>
    </gog-tab>
  }
</gog-tabs>
<!-- Off: a track, shown while the pointer is over the row, reaches what is off-screen. -->
<gog-tabs size="sm" ariaLabel="Month" [scrollActiveIntoView]="false">
  @for (month of months; track month) {
    <gog-tab [label]="month">
      <p>{{ month }}.</p>
    </gog-tab>
  }
</gog-tabs>

An activeIndex that names a disabled tab

The tablist shows the first enabled tab rather than nothing — but activeIndex keeps the value it was given, so the bound value and the tab on screen disagree. Bind indexes of enabled tabs.

Billing.

activeIndex: 1

<div>
  <gog-button variant="outline" size="sm" (gogClick)="activeIndex.set(2)">
    activeIndex = 2 (disabled)
  </gog-button>
  <gog-button variant="outline" size="sm" (gogClick)="activeIndex.set(1)"
    >activeIndex = 1</gog-button
  >
</div>
<gog-tabs ariaLabel="Account" [(activeIndex)]="activeIndex">
  <gog-tab label="Profile"><p>Profile.</p></gog-tab>
  <gog-tab label="Billing"><p>Billing.</p></gog-tab>
  <gog-tab label="Audit" disabled><p>Audit.</p></gog-tab>
</gog-tabs>

<p>activeIndex: {{ activeIndex() }}</p>

Eager or lazy content

Content written directly inside a <gog-tab> renders eagerly and is merely hidden while inactive — right for cheap content, because scroll position, unsubmitted input and any state the DOM holds survive a switch. Wrap it in an <ng-template gogTabContent> and it is built on first activation and kept alive after. Which you get is decided by whether that template is present — there is no lazy input to keep in sync with it.

Eager and lazy, side by side

Type in the first tab, switch away and back: the text is still there. The third tab's content is not in the DOM until you open it.

<gog-tabs ariaLabel="Content">
  <!-- Eager: built at once, only hidden while inactive, so it keeps what was typed. -->
  <gog-tab label="Eager">
    <gog-inputfield label="Draft" placeholder="Type, switch away, come back" />
  </gog-tab>
  <gog-tab label="Another"><p>Switch back: the draft is still there.</p></gog-tab>
  <!-- Lazy: built the first time its tab is shown, then kept. -->
  <gog-tab label="Lazy">
    <ng-template gogTabContent>
      <p>Built on first activation — this was not in the DOM until now.</p>
    </ng-template>
  </gog-tab>
</gog-tabs>

Accessibility

The headers form a real tablist, and each panel is a tabpanel labelled by its header.

  • Name — set ariaLabel on <gog-tabs> to say what the tabs switch between ("Account settings"); each tab is named by its label. Only the app knows that name, so an unnamed tablist logs one console.warn per page in dev mode 21.19.0, never in production.
  • Keyboard — one tab stop for the whole row. The arrow keys move between tabs following orientation — a horizontal tablist leaves ArrowDown to the page — and Home / End jump to the ends. Activation follows focus, the automatic variant of the ARIA tabs pattern. Disabled tabs are skipped rather than merely unclickable.
  • Panels — each panel is focusable, so tabbing out of the tablist lands in the content.

API Reference

gog-tabs — Inputs

NameTypeDefaultDescription
scrollActiveIntoViewbooleantrueWith an overflowing header row, selecting a tab scrolls it into view — instantly on first render, smoothly afterwards (and instantly under prefers-reduced-motion).
showScrollTrackboolean | undefinedundefinedWhether the header row shows a scrollbar track. Unset it follows scrollActiveIntoView: hidden while that is on (the scrolling is driven for you), shown once it is off, where the track is the only hint that there is more to reach.
activeIndexnumber0Index of the visible tab. Two-way bindable with [(activeIndex)].
align'start' | 'center' | 'end' | 'stretch''start'How the headers distribute along the tablist. stretch makes them share the width.
orientation'horizontal' | 'vertical''horizontal'Which way the tablist runs.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Header typography and padding.
fullWidthbooleanfalseStretches the whole component to fill its container.
ariaLabelstring''Names the tablist: what the tabs switch between ("Account settings"). Unset, it warns in dev mode (since 21.19.0).
rippleboolean | undefinedundefinedPress ripple on each tab header. Unset, falls back to GOG_CONFIG.ripple.enabled, which is off by default; setting it here wins over the app-wide value in both directions.

gog-tabs — Outputs

NamePayloadDescription
gogTabChangenumberEmitted with the new index when the active tab changes.
activeIndexChangenumberThe activeIndex model’s change event, for [(activeIndex)].

gog-tab — Inputs

NameTypeDefaultDescription
labelstring''Header text. A tab declares its own header, so it is defined in exactly one place.
iconNameGogIconName | nullnullOptional leading icon in the header.
disabledbooleanfalseMakes the tab unreachable by click and skipped by arrow navigation.

Content slots

DirectiveContextDescription
gogTabHeader$implicit (the gog-tab), active, disabled, indexOn an <ng-template> inside gog-tabs. Replaces every header button's content.
gogTabContentnoneOn an <ng-template> inside a gog-tab. Makes that tab's content lazy — built on first activation, kept alive after.

Global Configuration

Set any of these once with provideGogConfig() instead of repeating them on every instance — an instance's own input still wins when it sets one itself. See Global Configuration for the full reference.

  • GOG_CONFIG.ripple.enabled

This site is not on the default here. The library ships ripple.enabled as false; these docs set it to true app-wide so the demos above actually show the press feedback. In a fresh app you get no ripple until you ask for one — the droplet button in the header switches this site between the two, and it is on right now.

Styling Tokens

Every CSS custom property the tabs paint with. Override any of them — on a single instance, a subtree, or a theme — to restyle them. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-tabs-rest-color / -hover-color / -active-colorTab header label, per state.
--gog-tabs-press-bg / -press-colorA header under a press. It carries a label colour as well as a background, the way the button does, because a header has little fill of its own to deepen.
--gog-tabs-indicator-color / -indicator-thickness / -indicator-radiusThe bar marking the active tab.
--gog-tabs-header-border-color / -header-border-width / -header-border-styleThe rule under the tablist.
--gog-tabs-{size}-font-size / -{size}-paddingHeader typography and padding, per size step (sm/md/lg/slg).
--gog-tabs-tab-gap / -gap / -icon-sizeGap between headers, between a header’s icon and its label, and icon size.
--gog-tabs-panel-padding / -panel-colorThe content panel below the tablist.
--gog-tabs-focus-ring-color / -focus-ring-width / -focus-ring-offset / -disabled-opacityKeyboard focus ring and the disabled state.