GUILD OF GLEKS UIv21.19.0

gog-button  ·  [gogButton]

Button

A debounced action button with four variants, five sizes, and built-in loading, disabled, and full-width states — plus, since 21.4.0, a [gogButton] directive that gives the same look to a link you own.

Overview

Import the component and drop it into a template.

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

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

Basic usage — a primary button that reacts to a click. Listen to (gogClick), not (click): gogClick is the one that respects debounce and loading.

Clicked 0 time(s).

<gog-button variant="primary" (gogClick)="onClick()">Click me</gog-button>
<p>Clicked {{ clicks() }} time(s).</p>

Examples

Variants & sizes

Every combination of the four variants and five sizes.

primary
secondary
outline
ghost
@for (variant of variants; track variant) {
  <div>
    <span>{{ variant }}</span>
    @for (size of sizes; track size) {
      <gog-button [variant]="variant" [size]="size">{{ size }}</gog-button>
    }
  </div>
}

Severity

severity says what the action means; variant says how loudly it is drawn. The two are orthogonal, so this is not a fifth variant — every cell below is a real combination, and a ghost delete is still a delete. "accent" is the default and the absence of a claim, which is why every other button on this page needs no opt-out.

success
danger
warning
info
@for (severity of severities; track severity) {
  <div>
    <span>{{ severity }}</span>
    @for (variant of variants; track variant) {
      <gog-button [variant]="variant" [severity]="severity">{{ variant }}</gog-button>
    }
  </div>
}

Now switch the theme with the toggle in the header and look again. Three decisions show at once. A filled button's label is the colour its theme states for that status, per status: under primeng, success, warning and info carry a near-black label because white would be unreadable on them, while danger keeps white. Hover and press deepen the fill away from that label, so a state only makes it easier to read. And the outlined and ghost labels are the status hue mixed halfway toward the page's ink, because the raw hue as body text clears WCAG AA in only five of the eleven themes. The Theming guide describes the layering behind it.

Press feedback, with animations off

Hold any of these down. The background deepens one step past its own hover, so the press reads even while the pointer is already hovering — and it is a state rather than a movement. Turn on prefers-reduced-motion: reduce (DevTools → Rendering → Emulate CSS media feature) and the scale() goes away while the colour stays. The last button sets its own press colour inline, through the instance tokens --gog-button-press-bg / --gog-button-press-color.

@for (variant of variants; track variant) {
  <gog-button [variant]="variant">{{ variant }}</gog-button>
}

<!-- One instance with its own press colour: the instance tier, set inline. -->
<gog-button
  variant="primary"
  style="--gog-button-press-bg: var(--gog-danger-color); --gog-button-press-color: #fff"
>
  custom press
</gog-button>

A theme sets the same thing for every button of a variant, and retimes or removes the movement for all of them:

css
:root {
  /* Every primary button, pressed. One token per variant. */
  --gog-button-primary-press-bg: #7a1d1d;
  /* The press movement; 1 removes it, everywhere. */
  --gog-button-active-scale: 1;
}

Until 21.9.0 the scale was the whole press, so with animations off a press showed nothing. The ripple is not meant to cover that: it is off by default and suppressed under reduced motion, because a ripple is decoration and a press state is not.

Disabled

One disabled button per variant — the disabled state must stay legible on every colour.

@for (variant of variants; track variant) {
  <gog-button [variant]="variant" disabled>{{ variant }}</gog-button>
}

Loading

Loading swaps the label for a spinner and blocks clicks — through aria-disabled rather than the native disabled, so focus stays on the button. On a type="submit" button a click while loading does not submit the form. The spinner scales with the button size.

<div>
  <gog-button variant="primary" [loading]="saving()" (gogClick)="save()">Save</gog-button>
</div>

<!-- The spinner scales with the button. -->
<div>
  @for (size of sizes; track size) {
    <gog-button
      variant="secondary"
      [size]="size"
      [loading]="loading() === size"
      (gogClick)="load(size)"
    >
      {{ size }}
    </gog-button>
  }
</div>

Full width

fullWidth stretches the button to its container — the dashed box here. The directive takes the same input, on a <button> or a link.

<div>
  <gog-button fullWidth>gog-button fullWidth</gog-button>
</div>
<div>
  <button gogButton fullWidth variant="outline" type="button">button[gogButton] fullWidth</button>
</div>
<div>
  <a gogButton fullWidth variant="ghost" routerLink="/components/button">a[gogButton] fullWidth</a>
</div>

Content and icons

Text, an icon beside text, an icon alone, and a label too long for one line. An icon-only button has no visible label, so ariaLabel is required — it names the inner <button>, unlike a plain aria-label attribute on <gog-button>. Beside a label, put the icon in as a plain <gog-icon>: it is centred and spaced --gog-button-gap away, with no margin or &nbsp; of your own. Every button of one size is one height, icon or not 21.15.0 — read each column down. A long label wraps once its container is narrower than it, and the button grows taller with it.

text
icon + text
icon only
long text
<div>
  <span>text</span>
  @for (size of sizes; track size) {
    <gog-button [size]="size">Save</gog-button>
  }
</div>

<!-- An icon beside a label: no margin or &nbsp; of your own. -->
<div>
  <span>icon + text</span>
  @for (size of sizes; track size) {
    <gog-button [size]="size">
      <gog-icon name="check" />
      Save
    </gog-button>
  }
</div>

<!-- No visible label, so ariaLabel names the inner <button>. -->
<div>
  <span>icon only</span>
  @for (size of sizes; track size) {
    <gog-button [size]="size" ariaLabel="Close">
      <gog-icon name="close" />
    </gog-button>
  }
</div>

<div>
  <span>long text</span>
  <gog-button>Export every selected row to a spreadsheet</gog-button>
</div>

ARIA state — a toggle and a disclosure

The component hides the real <button>, so [attr.aria-pressed] written on <gog-button> lands on a host with no role and reaches no assistive tech — it compiles and looks right, which is why it is worth a demo. Use the inputs: ariaPressed, ariaExpanded, ariaControls, ariaHasPopup and ariaCurrent21.15.0 — the last one marks the current item of a set, the way gog-paginator marks its current page.

pressed
expanded
current
<!-- A toggle: false is "a toggle that is off", null would be "not a toggle". -->
<div>
  <span>pressed</span>
  <gog-button variant="outline" [ariaPressed]="mirrored()" (gogClick)="toggleMirror()">
    Mirror layout
  </gog-button>
  <gog-button variant="outline" ariaPressed="mixed">Some rows selected</gog-button>
</div>

<!-- A disclosure: it states what it opens and whether it is open. -->
<div>
  <span>expanded</span>
  <gog-button
    variant="outline"
    [ariaExpanded]="filtersOpen()"
    ariaControls="filters-region"
    ariaHasPopup="dialog"
    (gogClick)="toggleFilters()"
  >
    Filters
  </gog-button>
</div>

<!-- The current item of a set: on that one button only. -->
<div>
  <span>current</span>
  @for (page of pages; track page) {
    <gog-button
      variant="ghost"
      size="sm"
      [ariaCurrent]="page === current() ? 'page' : null"
      [ariaLabel]="'Page ' + page"
      (gogClick)="current.set(page)"
    >
      {{ page }}
    </gog-button>
  }
</div>

<!-- aria-controls must name an element that exists, so this hides rather than leaves. -->
<p id="filters-region" [hidden]="!filtersOpen()">The region the Filters button controls.</p>

Press "Mirror layout": a toggle that is on keeps an inset ring (--gog-button-<variant>-toggled-shadow) for as long as aria-pressed is "true" or "mixed" — a ring rather than a fill, because hover and press already own the background. The off state renders aria-pressed="false" rather than dropping the attribute: null means "not a toggle button", false means "a toggle that is off", and to a screen reader those are two different controls.

Debounce guard

Clicks are throttled leading-edge: the first fires immediately, further clicks are dropped for debounce ms (default 300). Click each one rapidly and compare the counters: 0 accepts every click, 1000 one a second. A dropped click is cancelled, so on a type="submit" button it does not submit the form either.

default (300)0
[debounce]="0"0
[debounce]="1000"0
<div>
  <span>default (300)</span>
  <gog-button (gogClick)="count('default')">Click me fast</gog-button>
  <code>{{ clicks().default }}</code>
</div>
<div>
  <span>[debounce]="0"</span>
  <gog-button [debounce]="0" (gogClick)="count('zero')">Click me fast</gog-button>
  <code>{{ clicks().zero }}</code>
</div>
<div>
  <span>[debounce]="1000"</span>
  <gog-button [debounce]="1000" (gogClick)="count('slow')">Click me fast</gog-button>
  <code>{{ clicks().slow }}</code>
</div>

Native type semantics

type is forwarded to the native <button>, so a submit or reset button inside a <form> works as it would without the component — and it defaults to "button", so a button in a form submits only when you ask. A loading submit button does not submit.

type unset0 submits
type="submit"0 submits, 0 resets
submit, loading0 submits
<!-- type defaults to "button": inside a form it does not submit. -->
<form (submit)="submit($event, 'unset')">
  <span>type unset</span>
  <gog-button>Click</gog-button>
  <code>{{ submits().unset }} submits</code>
</form>

<form (submit)="submit($event, 'submit')" (reset)="resets.update((n) => n + 1)">
  <span>type="submit"</span>
  <gog-button type="submit">Submit</gog-button>
  <gog-button variant="outline" type="reset">Reset</gog-button>
  <code>{{ submits().submit }} submits, {{ resets() }} resets</code>
</form>

<!-- A loading button does not submit its form. -->
<form (submit)="submit($event, 'loading')">
  <span>submit, loading</span>
  <gog-button type="submit" loading>Submit</gog-button>
  <code>{{ submits().loading }} submits</code>
</form>

App-wide defaults — GOG_CONFIG

control.size and button.debounce set the default for every button under the provider; an instance's own input still wins. This example provides the config on itself so that it reaches only its own buttons — in an app it goes in app.config.ts. See Global Configuration for every key.

size unset
size="sm"
debounce 10000
<div>
  <span>size unset</span>
  <gog-button>Takes lg from the config</gog-button>
</div>
<div>
  <span>size="sm"</span>
  <gog-button size="sm">The instance wins</gog-button>
</div>
<div>
  <span>debounce 1000</span>
  <gog-button (gogClick)="clicks.update((n) => n + 1)">Click me fast</gog-button>
  <code>{{ clicks() }}</code>
</div>

gog-button renders its own <button>, so it can never be a link. The directive inverts that: the element stays yours and [gogButton] only gives it the look.

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

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

The component and the directive side by side, in every variant. The directive has no disabled, loading or ARIA inputs: those are attributes of the element it is written on, so a disabled one is a <button disabled>.

gog-button
button[gogButton]
a[gogButton]LinkLinkLinkLink
disabled
<div>
  <span>gog-button</span>
  @for (variant of variants; track variant) {
    <gog-button [variant]="variant">Button</gog-button>
  }
</div>

<div>
  <span>button[gogButton]</span>
  @for (variant of variants; track variant) {
    <button gogButton type="button" [variant]="variant">Button</button>
  }
</div>

<!-- A real link: routerLink, href and target work because they are yours. -->
<div>
  <span>a[gogButton]</span>
  @for (variant of variants; track variant) {
    <a gogButton [variant]="variant" routerLink="/general/theming">Link</a>
  }
</div>

<!-- Disabled is an attribute of a <button>; an <a> has no disabled state. -->
<div>
  <span>disabled</span>
  <gog-button disabled>gog-button</gog-button>
  <button gogButton type="button" disabled>button[gogButton]</button>
</div>

The selector is a[gogButton], button[gogButton] — deliberately not a bare [gogButton]. On a <div> the result would look like a button while being invisible to the keyboard and to assistive technology.

Which one to reach for

The component when the button acts on the page: it owns loading (a centred spinner it projects), debounce click throttling and the gogClick output — none of which a bare element can provide. The directive when the element must be a link, or must keep directives of its own. routerLink, href, target, download, type="submit" and the rest keep working because they were never brokered through an input in the first place.

That is also why the library has no @angular/router dependency — a component that took a routerLink input would force the router on every app that installs the package.

Two things the directive deliberately does not do: no disabled on an <a> (there is no such thing — drop the href or render a real <button>), and no loading state (the spinner is a projected child, which a directive cannot add without taking over the element's content). Its styles live in the global styles/button.css, pulled in by index.css, because emulated encapsulation cannot reach an element declared in your template.

Accessibility

gog-button renders a native <button>, so it is one tab stop, Enter and Space press it, and it is announced as a button by its content. Everything a screen reader needs goes on that inner element through inputs, never as attributes on the <gog-button> host:

  • Name — the projected text, or ariaLabel when there is none (an icon-only button).
  • State — ariaPressed for a toggle, ariaExpanded + ariaControls + ariaHasPopup for a disclosure or popup trigger, ariaCurrent21.15.0 for the current item of a set.
  • Disabled — disabled takes the button out of the tab order; loading keeps it focusable with aria-disabled, and keeps its label in the accessible name 21.15.0, so a button that was just pressed still says what it is.
  • Directives on a gog-button — gogTooltip, [gogMenuTrigger] and gogBadge write their ARIA onto the inner <button>21.15.0.

[gogButton] needs none of these inputs: it styles an element you own, so write the attributes on it directly — it draws the toggled ring off the aria-pressed you wrote.

API Reference

gog-button — Inputs

NameTypeDefaultDescription
variant'primary' | 'secondary' | 'outline' | 'ghost''primary'Visual style of the button.
severity'accent' | 'success' | 'danger' | 'warning' | 'info''accent'What the action means, as opposed to how loudly it is drawn. Orthogonal to variant, so every combination is real: a ghost delete is still a delete. accent is the absence of a claim and leaves the button exactly as it was.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Button size.
disabledbooleanfalseFully non-interactive: excluded from tab order via the native disabled attribute.
fullWidthbooleanfalseStretches the button to fill its container.
type'button' | 'submit' | 'reset''button'Forwarded to the native <button> type attribute.
loadingbooleanfalseShows a spinner in place of the label and blocks activation — including a type="submit" button's form submission. Uses aria-disabled rather than the native disabled attribute, so the button stays focusable, and keeps its label in the accessible name (hidden with opacity, not visibility) so it still reads as "Save".
debouncenumber300Minimum time, in ms, between accepted clicks. Leading-edge throttle: the first click fires immediately, further clicks are dropped until the window elapses. A dropped click is cancelled, so on a type="submit" button it does not submit the form either.
ariaLabelstring | nullnullAccessible name forwarded to the native <button>. Required for icon-only buttons — a plain aria-label attribute on <gog-button> lands on the host element, not the inner button, so assistive tech never sees it.
ariaPressedboolean | 'mixed' | nullnullMarks the button as a toggle and reports its state. null omits the attribute entirely; false renders aria-pressed="false", which is what an off toggle has to say — a button with no aria-pressed is not a toggle button.
ariaExpandedboolean | nullnullFor a disclosure or popup trigger: whether the thing it controls is currently open. Like ariaPressed, false is a real state and null means "this button expands nothing".
ariaControlsstring | nullnullId of the element this button controls. Pairs with ariaExpanded; point it at an element that is actually in the document.
ariaHasPopupGogAriaHasPopup | nullnullboolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' — what kind of popup the button opens.
ariaCurrent21.15.0GogAriaCurrent | nullnullMarks the current item of a set — 'page', 'step', 'location', 'date', 'time', or true — on the inner <button>. Set it on that one button only; null omits the attribute. gog-paginator uses it for its current page.
rippleboolean | undefinedundefinedPress ripple on the inner <button>. 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-button — Outputs

NamePayloadDescription
gogClickMouseEventEmitted on each accepted click — after debounce throttling, and never while loading.

[gogButton] — Inputs

NameTypeDefaultDescription
variant'primary' | 'secondary' | 'outline' | 'ghost''primary'Visual style — the same four the component offers.
severity'accent' | 'success' | 'danger' | 'warning' | 'info''accent'What the action means, as opposed to how loudly it is drawn. Orthogonal to variant, so every combination is real: a ghost delete is still a delete. accent is the absence of a claim. The same input the component takes.
size'xsm' | 'sm' | 'md' | 'lg' | 'slg''md'Also settable app-wide via GOG_CONFIG.control.size.
fullWidthbooleanfalseStretches the element to fill its container.

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.control.size
  • GOG_CONFIG.button.debounce
  • GOG_CONFIG.ripple.enabled
  • GOG_CONFIG.spinner.component — the spinner loading draws, which has no input of its own
  • GOG_CONFIG.spinner.variant — the same spinner, when no component is set

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 button 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-button-font-family / -font-weight / -letter-spacing / -text-transformLabel typography.
--gog-button-radiusCorner radius.
--gog-button-border-width / -styleBorder.
--gog-button-transition-durationHover / active transition timing.
--gog-button-{variant}-bg / -color / -border / -shadowFill, text, border and shadow per variant (primary/secondary/outline/ghost).
--gog-button-{variant}-hover-bg / -hover-color / -hover-shadowHover state per variant.
--gog-button-{variant}-press-bg / -press-colorPressed state per variant. The press is a colour and not only the scale below, so it survives prefers-reduced-motion.
--gog-button-focus-ring-color / -focus-ring-width / -focus-ring-offsetThe keyboard focus ring. Its colour is its own token since 21.13.0 and reads the accent; it used to follow each variant’s hover wash, which on ghost and the severity outline buttons made the ring invisible in four themes (1.07:1 at worst).
--gog-button-active-scaleHow far a press shrinks the button. Dropped under prefers-reduced-motion, where the press colour carries the state on its own.
--gog-button-{variant}-toggled-shadow / --gog-button-toggled-ring-widthThe inset ring a button with aria-pressed="true" (or "mixed") draws. A ring rather than a fill, because hover and press already own the background.
--gog-button-{status}-fill / -fill-hover / -fill-press / -on-fill / -ink / -washThe severity palette, per status (danger/success/warning/info). fill and on-fill are a filled button and its label; ink is the label of a transparent one, the status hue mixed halfway toward the page ink; wash is the hover background under it.
--gog-button-{variant}-spinner-colorThe loading spinner, per variant.
--gog-button-bg / -color / -border / -padding / -font-size / -press-bg / -press-color / -toggled-shadowUndeclared by default — the escape hatch for styling a single button instance.