GUILD OF GLEKS UIv21.19.0

gog-panel

Panel

A titled region of a page — a settings section, a dashboard area, a form group. Unlike gog-card it is a real landmark (role="region" named by its heading), it can collapse through the existing gog-collapsible primitive, and its surface is never itself a link: controls live inside a panel.

Overview

Import the component and the slot directives you use, then project a heading. The heading is what names the region — without one the panel is still a panel, it just has no accessible name.

typescript
import {
  GogPanelFooterDirective,
  GogPanelHeaderDirective,
  PanelComponent,
} from '@guildofgleks/ui';

@Component({
  // ...
  imports: [PanelComponent, GogPanelHeaderDirective, GogPanelFooterDirective],
})

Basic usage — a titled region of the page:

Notifications

The heading names the region, so a screen reader lists this section by name instead of announcing an unlabelled group.

<gog-panel size="md">
  <h3 gogPanelHeader>Notifications</h3>
  <p>
    The heading names the region, so a screen reader lists this section by name instead of
    announcing an unlabelled group.
  </p>
</gog-panel>

Examples

Variants and states

The same three variants as gog-card, from the shared GogSurfaceVariant type — elevated is the default here, since a page region is usually the raised thing on the page. Each is shown open, closed, disabled and loading; loading keeps the heading and replaces only the body. Hover and focus on the header row are live.

elevated, open

Sixteen events since Tuesday.

outlined, open

Sixteen events since Tuesday.

filled, open

Sixteen events since Tuesday.

elevated, closed

outlined, closed

filled, closed

elevated, disabled

outlined, disabled

filled, disabled

elevated, loading

Sixteen events since Tuesday.

outlined, loading

Sixteen events since Tuesday.

filled, loading

Sixteen events since Tuesday.

<!-- Collapsible throughout: closed and disabled are states of its toggle. -->
@for (state of states; track state.name) {
  @for (variant of variants; track variant) {
    <gog-panel
      [variant]="variant"
      size="md"
      collapsible
      [open]="state.open"
      [disabled]="state.disabled"
      [loading]="state.loading"
    >
      <h4 gogPanelHeader>{{ variant }}, {{ state.name }}</h4>
      <p>Sixteen events since Tuesday.</p>
    </gog-panel>
  }
}

Sizes

size drives padding and the gap between rows on the same five-step scale as every control. Each panel here hugs its content, so the padding is what sets the box.

xsm

Same copy, every tier.

sm

Same copy, every tier.

md

Same copy, every tier.

lg

Same copy, every tier.

slg

Same copy, every tier.

<!-- Each panel hugs its content, so the padding size drives is what sets the box. -->
@for (size of sizes; track size) {
  <gog-panel [size]="size" variant="outlined">
    <h4 gogPanelHeader>{{ size }}</h4>
    <p>Same copy, every tier.</p>
  </gog-panel>
}

Collapsible

collapsible adds the toggle and composes gog-collapsible underneath, so the open/close state, the id wiring and the animation are the library's existing ones. The heading stays a heading: the toggle is a separate <button> named by it through aria-labelledby, with its hit area stretched across the header row — so the pointer still gets "click the title to collapse", while a screen reader gets a heading and a named expandable button rather than a heading swallowed by role="button". Without a header the toggle falls back to GOG_CONFIG.labels.togglePanel.

Notifications

Security

Billing (disabled)

The toggle is aria-disabled and does nothing; the content stays readable.

<gog-panel collapsible [(open)]="notificationsOpen" size="md">
  <h4 gogPanelHeader>Notifications</h4>
  <gog-checkbox label="Email digest" [(checked)]="emailDigest" />
  <gog-checkbox label="Push alerts" [(checked)]="pushAlerts" />
  <div gogPanelFooter>
    <gog-button size="xsm" variant="outline">Reset</gog-button>
    <gog-button size="xsm">Save</gog-button>
  </div>
</gog-panel>

<gog-panel collapsible [(open)]="securityOpen" size="md" variant="outlined">
  <h4 gogPanelHeader>Security</h4>
  <p>Closed to begin with — <code>open</code> is a model, so it binds both ways.</p>
</gog-panel>

<gog-panel collapsible [(open)]="billingOpen" disabled size="md">
  <h4 gogPanelHeader>Billing (disabled)</h4>
  <p>The toggle is <code>aria-disabled</code> and does nothing; the content stays readable.</p>
</gog-panel>

A panel that holds an overlay

A non-collapsible panel undoes the collapse geometry it inherits, overflow included, so a dropdown or menu opened inside one escapes the panel's box with nothing extra asked of you — the first select below.

A collapsible one clips only while it opens and closes, exactly like gog-collapsible, and stops once it is open and settled 21.15.0 — so the second select escapes as well. Before 21.15.0 an open collapsible panel kept clipping, and an overlay inside needed [appendToBody]. It still does in one case: content capped with --gog-collapsible-max-height never settles, and keeps clipping.

Regional

Regional, collapsible

<!--
    Not collapsible: the panel undoes the collapse geometry it inherits, `overflow` included,
    so this dropdown escapes the panel's box with nothing extra asked of you.
  -->
<gog-panel size="md" variant="outlined">
  <h4 gogPanelHeader>Regional</h4>
  <gog-select label="Time zone" [options]="timezones" [(value)]="plain" />
</gog-panel>

<!--
    Collapsible: it clips only while it opens and closes, so once open the dropdown escapes too.
    Content capped with --gog-collapsible-max-height still clips; use [appendToBody] there.
  -->
<gog-panel collapsible [(open)]="regionalOpen" size="md" variant="outlined">
  <h4 gogPanelHeader>Regional, collapsible</h4>
  <gog-select label="Time zone" [options]="timezones" [(value)]="inCollapsible" />
</gog-panel>

Loading

The heading stays — a page section is titled before its content arrives, and blanking the title would move the layout twice — and only the body is replaced with skeletonLines placeholder lines. The footer stays too, so its actions remain usable. The host is marked aria-busy while it lasts.

Activity

Sixteen events since Tuesday, most of them from the nightly import.

<div>
  <gog-button size="xsm" variant="outline" (gogClick)="toggle()">
    {{ loading() ? 'Finish loading' : 'Load again' }}
  </gog-button>
</div>
<!-- Loading keeps the heading: a section is titled before its content arrives. -->
<gog-panel [loading]="loading()" [skeletonLines]="4" size="md">
  <h4 gogPanelHeader>Activity</h4>
  <p>Sixteen events since Tuesday, most of them from the nightly import.</p>
  <div gogPanelFooter>
    <gog-button size="xsm" variant="ghost">Export</gog-button>
  </div>
</gog-panel>

Theming

Every value comes from a --gog-panel-* token, and the instance tier is undeclared on purpose — setting one on an element beats the variant and size classes without a specificity fight, and without ::ng-deep. See Theming for the full list, and the note there about this prefix naming two different things.

Overridden per instance

Three instance tokens on the element. No ::ng-deep.

<!-- Instance tokens, inline: they beat the variant and size classes without a fight. -->
<gog-panel
  size="md"
  style="
    --gog-panel-elevated-bg: color-mix(in srgb, var(--gog-accent-color) 10%, transparent);
    --gog-panel-radius: 14px;
    --gog-panel-heading-color: var(--gog-accent-color);
  "
>
  <h4 gogPanelHeader>Overridden per instance</h4>
  <p>Three instance tokens on the element. No <code>::ng-deep</code>.</p>
</gog-panel>

Panel or card?

Both paint a surface, and the library ships them as two components because they answer different questions. The quickest test is about links:

  • Is the whole surface a link? Then it is a gog-card with a gogCardLink. A panel is never a link — there is no gogPanelLink, because a region that is a link cannot hold the controls a panel exists to hold.
  • Otherwise: a panel is a titled region of a page — a landmark, one of a handful, and it can collapse. A card is one self-contained thing, usually one of many in a grid, and announces as role="group" so twenty of them do not bury the landmark list.

Accessibility

A panel with a heading is a named landmark region; a collapsible one adds a real toggle button.

  • Name — gogPanelHeader on your own heading names the region, so a screen reader lists the section by name. Keep panels to a handful per page: each one is a landmark.
  • Collapsing — the header row holds a button with aria-expanded and aria-controls; Enter or Space toggles it. Closed content is inert. A disabled panel's toggle is aria-disabled and its content stays readable.
  • Loading marks the panel aria-busy and keeps the heading.

API Reference

Inputs

NameTypeDefaultDescription
variantGogSurfaceVariant'elevated''outlined' | 'elevated' | 'filled'. Elevated is the default here, because a page region is usually the raised thing on the page.
sizeGogSize'lg'Drives padding and the gap between the panel’s rows, on the five-tier scale.
collapsiblebooleanfalseAdds the toggle and composes gog-collapsible underneath. A collapsible panel clips while it animates, and since 21.15.0 stops once open, so an overlay inside it is not cut off.
disabledbooleanfalseMarks the toggle aria-disabled and stops it acting; the content stays readable.
loadingbooleanfalseReplaces the body with placeholder lines and sets aria-busy. The heading and footer stay put.
skeletonLinesnumber3How many placeholder lines the loading body draws.

Models

NameTypeDefaultDescription
openbooleantrueTwo-way bindable. Ignored while collapsible is off. Emits openChange, so [(open)] works.

Slots — attribute directives on your own elements

SelectorGoes onDescription
gogPanelHeaderan element of yoursAttribute directive on your own heading. Becomes the region’s accessible name and the toggle’s label.
gogPanelFooteran element of yoursAttribute directive on your own element. Sits below the body, above the panel’s edge, and survives loading.

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.labels.togglePanel — only when the panel has no gogPanelHeader

Styling Tokens

gog-panel shares its token prefix with the foundation surface tier on purpose: --gog-panel-radius, --gog-panel-shadow and the border pair are the same tokens dialogs and dropdown panels read, so a theme's idea of a raised surface reaches this component for free. Everything else below is the component's own family.

--gog-panel-shadow is still the token you override for this surface, but since 21.12.0 its value is a step off a six-height elevation ladder rather than a hand-written shadow. A theme that turns the ladder's knobs moves this panel, a dropdown, a toast and a modal dialog together and keeps the order between them — which is the edit a theme actually wants, and what eleven themes hand-writing twenty-two shadow values could not do.

TokenDescription
--gog-panel-radius / --gog-panel-shadow / --gog-panel-border-width / --gog-panel-border-styleShared with the foundation surface tier — the same four tokens dialogs and dropdown panels read, so a theme’s idea of a raised surface reaches gog-panel for free. Setting them here restyles those surfaces too.
--gog-panel-outlined-bg / -outlined-border-color / -outlined-shadowThe outlined variant: a border, no shadow.
--gog-panel-elevated-bg / -elevated-border-colorThe elevated variant (the default) — takes the shared surface shadow above.
--gog-panel-filled-bg / -filled-border-color / -filled-shadowThe filled variant: a tint, neither border nor shadow.
--gog-panel-color / --gog-panel-font-familyBody text color and font stack.
--gog-panel-heading-color / -heading-font-family / -heading-font-size / -heading-font-weight / -heading-line-heightThe projected gogPanelHeader heading.
--gog-panel-header-gapGap between the heading and the collapse toggle.
--gog-panel-toggle-size / -toggle-color / -toggle-hover-bg / -toggle-radius / --gog-panel-chevron-sizeThe collapse toggle button and its chevron.
--gog-panel-footer-border-color / -footer-gap / -footer-padding-topThe projected gogPanelFooter row and the rule above it.
--gog-panel-xsm-padding-y … --gog-panel-slg-padding-y (and -padding-x, -gap)Padding and row gap per size tier, xsm through slg.
--gog-panel-focus-ring / -focus-ring-width / -focus-ring-offsetFocus ring on the collapse toggle.
--gog-panel-disabled-opacity / --gog-panel-transition-durationDisabled dimming, and the collapse/hover transition.