GUILD OF GLEKS UIv21.19.0

gog-accordion

Accordion

An expandable content panel with single-open and multi-open modes, content projection for headers, chevrons and bodies, and a loading skeleton state.

Overview

Import the component and drop it into a template.

typescript
import { AccordionComponent } from '@guildofgleks/ui';

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

Basic usage — three sections, one disabled, the first expanded on load. The body comes from the gogAccordionContent template, which receives the item back, and gogToggle reports each press.

Ships within 2 business days via standard courier.

gogToggle: none yet

<gog-accordion [items]="items" expandFirst (gogToggle)="onToggle($event)">
  <ng-template gogAccordionContent let-item>
    <p>{{ item['body'] }}</p>
  </ng-template>
</gog-accordion>

<p>gogToggle: {{ lastToggle() }}</p>

Examples

Sizes and item states

Every size, from xsm through slg; lg is the default. States belong to items, not to the accordion: each one here holds an open item, a closed one and one disabled through disabled: true on the item object. A disabled header cannot be opened and keyboard navigation skips it. Hover, focus and press are live — the page cannot force them. The three smallest sizes look closer together than lg and slg, and that is correct: they all label at --gog-text-xs, and the chevron is a ratio of the header's own type, so it does not manufacture a difference the type does not have.

size: xsm

Ships within 2 business days via standard courier.

size: sm

Ships within 2 business days via standard courier.

size: md

Ships within 2 business days via standard courier.

size: lg

Ships within 2 business days via standard courier.

size: slg

Ships within 2 business days via standard courier.

<!-- Each accordion holds one open item, one closed and one disabled. -->
@for (size of sizes; track size) {
  <p>size: {{ size }}</p>
  <gog-accordion [items]="items" [size]="size" [openIds]="firstOpen">
    <ng-template gogAccordionContent let-item>
      <p>{{ item['body'] }}</p>
    </ng-template>
  </gog-accordion>
}

Loading skeleton

While loading is on, each row is a placeholder: one per item when the items are known, skeletonCount of them when items is still empty. The chevron gets a placeholder too — or none, with showChevron off — so the row that arrives has the silhouette of the one that waited.

items=[], skeletonCount=2

showChevron=false

<div>
  <gog-button variant="outline" (gogClick)="loading.set(!loading())">
    {{ loading() ? 'Finish loading' : 'Start loading' }}
  </gog-button>
</div>
<gog-accordion [items]="items" [loading]="loading()">
  <ng-template gogAccordionContent let-item>
    <p>{{ item['body'] }}</p>
  </ng-template>
</gog-accordion>

<!-- The items have not arrived: skeletonCount decides how many rows wait for them. -->
<p>items=[], skeletonCount=2</p>
<gog-accordion [items]="[]" loading [skeletonCount]="2" />

<p>showChevron=false</p>
<gog-accordion [items]="items" loading [showChevron]="false" />

Single and multi-open

By default opening one item closes the one that was open. multi lets items open independently. openIds is two-way, so the page can read which are open.

openIds: none

<div>
  <gog-toggle label="multi" [(checked)]="multi" />
</div>
<gog-accordion [items]="items" [multi]="multi()" [(openIds)]="openIds">
  <ng-template gogAccordionContent let-item>
    <p>{{ item['body'] }}</p>
  </ng-template>
</gog-accordion>

<p>openIds: {{ openList() }}</p>

Controlled open state

openIds is a model, so the app can also write it — the buttons set the whole set and the accordion follows.

<div>
  <gog-button variant="outline" (gogClick)="openAll()">Open all</gog-button>
  <gog-button variant="outline" (gogClick)="closeAll()">Close all</gog-button>
</div>
<gog-accordion [items]="items" multi [(openIds)]="openIds">
  <ng-template gogAccordionContent let-item>
    <p>{{ item['body'] }}</p>
  </ng-template>
</gog-accordion>

Header and chevron templates

gogAccordionHeader and gogAccordionChevron both receive the item and its open state. A header template renders inside the header button, so it holds markup and never another control. It renders as written 21.15.0: the theme's title casing applies to the default title only, so the lines above are not uppercased in the themes that uppercase headers. The default chevron rotates by itself; a template draws its own open and closed look, and nothing rotates underneath it.

gogAccordionHeader

gogAccordionChevron

<p>gogAccordionHeader</p>
<gog-accordion [items]="services">
  <!-- Rendered inside the header button, stacked: markup only, never another control. -->
  <ng-template gogAccordionHeader let-item let-open="open">
    <span><gog-icon [name]="item['icon']" [style.color]="item['color']" /> {{ item.title }}</span>
    <small>{{ open ? 'expanded' : item['subtitle'] }}</small>
  </ng-template>
  <ng-template gogAccordionContent let-item>
    <p>{{ item['body'] }}</p>
  </ng-template>
</gog-accordion>

<p>gogAccordionChevron</p>
<gog-accordion [items]="faq">
  <!-- A custom chevron draws its own state; nothing rotates underneath it. -->
  <ng-template gogAccordionChevron let-open="open">
    <gog-icon [name]="open ? 'minus' : 'plus'" />
  </ng-template>
  <ng-template gogAccordionContent let-item>
    <p>{{ item['body'] }}</p>
  </ng-template>
</gog-accordion>

An overlay inside the body

A body can hold a control whose panel runs past it — here a select of time zones in the last item. The body clips only while it animates; once it is open and settled it does not, so the list overlaps the end of the accordion and whatever follows it, the code block below included. Open the select to see it.

<gog-accordion [items]="items" [(openIds)]="openIds">
  <ng-template gogAccordionContent let-item>
    @if (item.id === 'region') {
      <gog-select label="Time zone" [options]="timezones" [(value)]="timezone" />
    } @else {
      <p>{{ item['body'] }}</p>
    }
  </ng-template>
</gog-accordion>

Heading level

headingLevel wraps each header in role="heading" at that aria-level, so screen-reader users can jump straight to a section. Leave it unset when the accordion isn't part of the page outline (e.g. nested in a card).

<!-- Each header button is wrapped in role="heading" aria-level="3". -->
<gog-accordion [items]="items" [headingLevel]="3">
  <ng-template gogAccordionContent let-item>
    <p>{{ item['body'] }}</p>
  </ng-template>
</gog-accordion>

Accessibility

Each header is a real <button> that says whether it is expanded and which body it controls; each body is a region named by its header.

  • Role and name — the header button carries aria-expanded and aria-controls; the body is role="region" with aria-labelledby pointing at its header. With headingLevel set, each button sits inside role="heading" at that aria-level.
  • Keyboard — Tab moves between headers and into an open body; Enter or Space toggles the focused item; ArrowDown and ArrowUp move focus to the next and previous header, wrapping at the ends; Home and End go to the first and last. Disabled headers are skipped.
  • Closed bodies stay in the DOM, aria-hidden and inert, so nothing inside them takes focus or is read out.
  • Templates — a custom chevron is aria-hidden like the default one; aria-expanded on the header is what says open. A header template must not hold another control: a button inside a button is invalid and unreachable.
  • Loading sets aria-busy="true" on the host. The skeleton rows are aria-hidden, so the accordion reads as "coming" rather than empty.

API Reference

Inputs

NameTypeDefaultDescription
itemsreadonly GogAccordionItem[][]The sections to render. Each item needs an id and title, and may set disabled.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''lg'Header/body padding, font size, and chevron size.
expandFirstbooleanfalseOpens the first item once items becomes non-empty. Fires only that one time — closing everything by hand does not reopen it, even if items is later replaced.
multibooleanfalseAllows more than one item open at once. Off by default: opening an item closes the rest.
loadingbooleanfalseRenders a shimmering skeleton row per item instead of real headers — for when the item list itself hasn't arrived yet.
skeletonCountnumber3How many skeleton rows to render while loading is true and items is still empty — the common case of "the list itself hasn't arrived yet", where there is no item count to derive a row count from. Ignored once items has entries: then one skeleton row is rendered per item, so the placeholder matches the eventual shape.
showChevronbooleantrueToggles the trailing chevron indicator.
headingLevel2 | 3 | 4 | 5 | 6 | undefinedundefinedWraps each header in role="heading" at this aria-level, so screen readers can navigate sections by heading. Leave unset when the accordion is not part of the document outline.
openIdsReadonlySet<string | number>new Set()Two-way bindable set of open item ids — drive the accordion externally with [(openIds)].
rippleboolean | undefinedundefinedPress ripple on each item 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.

Outputs

NamePayloadDescription
gogToggleGogAccordionToggleEventEmitted with the item and its new open state whenever a header is toggled.
openIdsChangeReadonlySet<string | number>The open set after a toggle. Comes from the openIds model input.

Content slots

DirectiveContextDescription
gogAccordionHeader$implicit (the item), openReplaces the header content (everything left of the chevron). Falls back to item.title. Rendered inside the header button, so it must not hold another control.
gogAccordionChevron$implicit (the item), openReplaces the trailing chevron icon. The library rotates only its own chevron; a template draws its own state. Ignored when showChevron is false.
gogAccordionContent$implicit (the item)The panel body, rendered once per item.

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 accordion paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

TokenDescription
--gog-accordion-border-color / -width / -styleHeader border.
--gog-accordion-text-color / -accent-colorText and accent color.
--gog-accordion-hover-bgHeader hover background. --gog-accordion-hover-ring was removed in 21.13.0: the hover never drew a ring, so nothing read it.
--gog-accordion-focus-ring-color / -widthThe keyboard focus ring, and its own colour since 21.12.0. The header’s :focus-visible outline used to read --gog-accordion-hover-ring, so a hover-weight colour was doing focus duty and missed 3:1 in all eleven themes. Hover and focus are different signals and now carry different colours.
--gog-accordion-press-bgHeader press background, one step past its own hover.
--gog-accordion-radius / -body-radiusCorner radius for the header and body.
--gog-accordion-header-bg / -body-bgHeader and body background.
--gog-accordion-header-gapGap between chevron and title.
--gog-accordion-transition-duration / -body-transition-duration / -chevron-transition-durationExpand/collapse animation timing.
--gog-accordion-{size}-padding-y / -x / -font-size / -chevron-size / -chevron-font-sizeHeader padding and font size, per size step (xsm/sm/md/lg/slg). The chevron is a ratio of the header’s own type since 21.11.0 — 1.4em of box, 1em of glyph, one value at every size — so the three smallest sizes, which all label at --gog-text-xs, now carry identical chevrons. Making it a ratio also surfaced a glyph that had been overflowing its own box at every size.