GUILD OF GLEKS UIv21.19.0

gog-card

Card

A surface for one self-contained thing — a product tile, a summary, a search result. What it adds over a .card class of your own is what a class cannot do: it takes its accessible name from the projected heading, it folds in loading and disabled, and gogCardLink makes the whole surface activate a real link — your <a>, with your routerLink still on it.

Overview

Import the component and the slots you use. The heading is what names the card — a card without one is an unnamed group, so it deliberately gets no role at all.

typescript
import {
  CardComponent,
  GogCardFooterDirective,
  GogCardHeaderDirective,
  GogCardLinkDirective,
  GogCardMediaDirective,
} from '@guildofgleks/ui';

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

Basic usage — a heading and a body:

Quarterly summary

The heading names the card: it takes that element's id and points its own aria-labelledby at it. Without a header a card is an unnamed group, so it gets neither.

<gog-card>
  <h3 gogCardHeader>Quarterly summary</h3>
  <p>
    The heading names the card: it takes that element's id and points its own
    <code>aria-labelledby</code> at it. Without a header a card is an unnamed group, so it gets
    neither.
  </p>
</gog-card>

Examples

Variants and states

The same three variants as gog-panel, from the shared GogSurfaceVariant type — but outlined is the default here, because a grid of many cards wants a border rather than twenty shadows; elevated takes the shared surface shadow, filled is a tint with neither. Each is shown at rest, disabled and loading. Hover lifts the link's colour and focus rings the whole surface — live, so point at one or Tab to it.

outlined

at rest — revenue is up 12% on the quarter.

outlined

disabled — revenue is up 12% on the quarter.

outlined

loading — revenue is up 12% on the quarter.

elevated

at rest — revenue is up 12% on the quarter.

elevated

disabled — revenue is up 12% on the quarter.

elevated

loading — revenue is up 12% on the quarter.

filled

at rest — revenue is up 12% on the quarter.

filled

disabled — revenue is up 12% on the quarter.

filled

loading — revenue is up 12% on the quarter.

<!-- Every card holds a gogCardLink: disabled is mostly about what happens to that link. -->
@for (variant of variants; track variant) {
  @for (state of states; track state) {
    <gog-card [variant]="variant" [disabled]="state === 'disabled'" [loading]="state === 'loading'">
      <h4 gogCardHeader>
        <a gogCardLink routerLink="/components/card" fragment="examples">{{ variant }}</a>
      </h4>
      <p>{{ state }} — revenue is up 12% on the quarter.</p>
    </gog-card>
  }
}

Sizes

size drives padding and the gap between the card's rows on the same five-step scale as every control; loading placeholders take the card's size too.

xsm

Padding and row gap follow the size.

sm

Padding and row gap follow the size.

md

Padding and row gap follow the size.

lg

Padding and row gap follow the size.

slg

Padding and row gap follow the size.

<!-- Each card hugs its content, so the padding size drives is what sets the box. -->
@for (size of sizes; track size) {
  <gog-card [size]="size">
    <h4 gogCardHeader>{{ size }}</h4>
    <p>Padding and row gap follow the size.</p>
  </gog-card>
}

Interactive — the whole surface activates one real link

There is no interactive input and no gogClick output. A card becomes interactive by containing a gogCardLink, which stretches that link's hit area over the whole surface. The link stays yours, so routerLink, href, target, middle-click, "open in new tab" and Enter all behave normally, and the focus ring is drawn around the card.

Anything else focusable in the card still receives its own clicks — press the footer button and watch the tally, then click anywhere else on the card and follow the link instead.

Ada Lovelace

Mathematician

Alan Turing

Logician

Footer clicks that reached their own button: 0

@for (person of people; track person.id) {
  <gog-card>
    <h4 gogCardHeader>
      <a gogCardLink routerLink="/components/card" [fragment]="person.id">{{ person.name }}</a>
    </h4>
    <p>{{ person.role }}</p>
    <div gogCardFooter>
      <gog-tag variant="info" size="xsm">Profile</gog-tag>
      <gog-button size="xsm" variant="ghost" (gogClick)="shortlist()">Shortlist</gog-button>
    </div>
  </gog-card>
}

<p>Footer clicks that reached their own button: {{ footerClicks() }}</p>

Two costs, inherent to the pattern rather than to this implementation: text in the card cannot be selected by dragging, and a second link is reachable by keyboard but not by clicking the surface around it. If either matters, do not stretch the link — put an ordinary link in the heading and leave the surface inert. gogCardLink applies to <a> and <button> only. On a <div> it does nothing, on purpose: a div with a click handler is the thing this directive exists to stop you writing.

Media

gogCardMedia runs full-bleed to the card's edges and rounds into its top corners. The rendered order of the slots is fixed by the component — media, heading, body, footer — and does not follow the order you write them in: the two cards below are authored in opposite orders and render identically, which is what keeps a grid aligned when one card happens to be written differently from its neighbours.

Media written first

Full-bleed to the card's edges, rounded into its top corners.

Media written last

Authored after the heading and the body, and rendered identically to the card beside it.

<gog-card>
  <img [src]="mediaSrc" gogCardMedia alt="" height="120" />
  <h4 gogCardHeader>Media written first</h4>
  <p>Full-bleed to the card's edges, rounded into its top corners.</p>
</gog-card>

<!-- Written last, rendered the same: the component fixes the slot order. -->
<gog-card>
  <h4 gogCardHeader>Media written last</h4>
  <p>Authored after the heading and the body, and rendered identically to the card beside it.</p>
  <img [src]="mediaSrc" gogCardMedia alt="" height="120" />
</gog-card>

The bleed is inline-size: calc(100% + 2 * padding-x) plus a negative inline margin, so do not give the media a width of your own — a width: 100% overrides that calculation and the picture ends one padding short of the card's right edge while still starting flush at its left.

Loading and disabled

loading swaps the content for a title bar plus skeletonLines body lines and marks the host aria-busy. disabled dims the card, sets aria-disabled, and takes its link out of the tab order. Both make the card's link non-clickable.

loading is the first-paint treatment. For a refresh of a card that already has content, project a gog-spinner-overlay instead — replacing real content with placeholders is a worse answer once the reader has something to look at.

Quarterly summary

Revenue is up 12% on the quarter, driven mostly by renewals rather than new business.

Archived report

Tab through the pair: only the enabled card's link stops.

<div>
  <gog-card [loading]="loading()" [skeletonLines]="3">
    <h4 gogCardHeader>Quarterly summary</h4>
    <p>Revenue is up 12% on the quarter, driven mostly by renewals rather than new business.</p>
  </gog-card>
  <gog-button size="xsm" variant="outline" (gogClick)="toggleLoading()">
    {{ loading() ? 'Finish loading' : 'Load again' }}
  </gog-button>
</div>

<div>
  <gog-card [disabled]="disabled()">
    <h4 gogCardHeader>
      <a gogCardLink routerLink="/components/card">Archived report</a>
    </h4>
    <p>Tab through the pair: only the enabled card's link stops.</p>
  </gog-card>
  <gog-button size="xsm" variant="outline" (gogClick)="toggleDisabled()">
    {{ disabled() ? 'Enable' : 'Disable' }}
  </gog-button>
</div>

Theming

Every value comes from a --gog-card-* token, and the instance tier (--gog-card-bg, --gog-card-border-color, --gog-card-shadow, --gog-card-padding-y, --gog-card-padding-x, --gog-card-gap) is left undeclared on purpose, so setting one on an element beats the variant and size classes without a specificity fight.

Overridden per instance

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

<!-- Instance tokens, inline: the library leaves them undeclared, so they win without a fight. -->
<gog-card
  style="
    --gog-card-bg: color-mix(in srgb, var(--gog-accent-color) 10%, transparent);
    --gog-card-border-color: var(--gog-accent-color);
    --gog-card-heading-color: var(--gog-accent-color);
  "
>
  <h4 gogCardHeader>Overridden per instance</h4>
  <p>Three instance tokens on the element. No <code>::ng-deep</code>.</p>
</gog-card>

Card or panel?

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 card, with a gogCardLink. A gog-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 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. A panel is a titled region of a page — a real landmark, one of a handful, and it can collapse.

Accessibility

A card with a heading is a named group; without one it is a plain element.

  • Name — gogCardHeader on your own heading: the card takes its id and points aria-labelledby at it, with role="group". A card without a heading gets neither, rather than an unnamed group.
  • Link — gogCardLink is your <a> or <button>, so the card is one tab stop that Enter follows, named by the link text; the focus ring is drawn around the card. Other controls in the card keep their own tab stops and clicks.
  • State — loading marks the host aria-busy; disabled sets aria-disabled and takes the link out of the tab order.

API Reference

Inputs

NameTypeDefaultDescription
variantGogSurfaceVariant'outlined''outlined' | 'elevated' | 'filled'. Outlined is the default — a border and no shadow, which is what a grid of many wants.
sizeGogSize'md'Drives padding and the gap between the card’s rows, on the five-tier scale.
disabledbooleanfalseDims the card, sets aria-disabled, and takes the card link out of the tab order.
loadingbooleanfalseReplaces the content with a title bar plus skeletonLines text lines and sets aria-busy. The first-paint treatment, not a refresh.
skeletonLinesnumber2How many body lines the loading placeholder draws.

Slots — attribute directives on your own elements

SelectorGoes onDescription
gogCardHeaderan element of yoursYour own heading. The card takes its id (minting one if needed), points aria-labelledby at it, and announces as role="group". Without it the card gets neither.
gogCardMediaan element of yoursRuns full-bleed to the card’s edges and rounds into its top corners. Rendered above the heading whatever order you write it in.
gogCardFooteran element of yoursRendered last, below the body. Its controls keep their own clicks.
gogCardLinkan element of yoursOn your own <a> or <button>: stretches that link’s hit area over the whole card. Ignored on any other element, deliberately.

Global Configuration

This component has no GOG_CONFIG entries of its own — every default is set per instance. See Global Configuration for what does apply app-wide.

Styling Tokens

Every CSS custom property the card 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-card-bg / -border-color / -shadow / -padding-y / -padding-x / -gapThe instance tier — left undeclared by the library on purpose, so setting one on an element beats the variant and size classes without a specificity fight.
--gog-card-outlined-bg / -outlined-border-color / -outlined-shadowThe outlined variant (the default): a border, no shadow.
--gog-card-elevated-bg / -elevated-border-color / -elevated-shadowThe elevated variant: the shared surface shadow, no border.
--gog-card-filled-bg / -filled-border-color / -filled-shadowThe filled variant: a tint, neither border nor shadow.
--gog-card-color / --gog-card-font-family / --gog-card-radiusBody text color, font stack and corner radius.
--gog-card-heading-color / -heading-font-family / -heading-font-size / -heading-font-weight / -heading-line-heightThe projected gogCardHeader. The visual size comes from these regardless of which heading level you use.
--gog-card-footer-border-color / -footer-gap / -footer-padding-topThe projected gogCardFooter row and the rule above it.
--gog-card-hover-border-color / --gog-card-hover-shadowHover treatment, which only appears on a card holding a gogCardLink.
--gog-card-focus-ring / -focus-ring-width / -focus-ring-offsetThe ring drawn around the whole card when its stretched link takes focus.
--gog-card-xsm-padding-y … --gog-card-slg-padding-y (and -padding-x, -gap)Padding and row gap per size tier, xsm through slg.
--gog-card-disabled-opacity / --gog-card-transition-durationDisabled dimming, and the hover/focus transition.