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.
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.
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-buttonvariant="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.
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-buttonvariant="primary" [loading]="saving()" (gogClick)="save()">Save</gog-button></div><!-- The spinner scales with the button. --><div>
@for (size of sizes; track size) {
<gog-buttonvariant="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.
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 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 of your own. --><div><span>icon + text</span>
@for (size of sizes; track size) {
<gog-button [size]="size"><gog-iconname="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-iconname="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
The region the Filters button controls.
<!-- A toggle: false is "a toggle that is off", null would be "not a toggle". --><div><span>pressed</span><gog-buttonvariant="outline" [ariaPressed]="mirrored()" (gogClick)="toggleMirror()">
Mirror layout
</gog-button><gog-buttonvariant="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-buttonvariant="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-buttonvariant="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. --><pid="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 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-buttontype="submit">Submit</gog-button><gog-buttonvariant="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-buttontype="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-buttonsize="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>
Links that look like buttons — [gogButton]
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.
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>.
<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) {
<buttongogButtontype="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) {
<agogButton [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-buttondisabled>gog-button</gog-button><buttongogButtontype="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.
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.
disabled
boolean
false
Fully non-interactive: excluded from tab order via the native disabled attribute.
fullWidth
boolean
false
Stretches the button to fill its container.
type
'button' | 'submit' | 'reset'
'button'
Forwarded to the native <button> type attribute.
loading
boolean
false
Shows 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".
debounce
number
300
Minimum 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.
ariaLabel
string | null
null
Accessible 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.
ariaPressed
boolean | 'mixed' | null
null
Marks 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.
ariaExpanded
boolean | null
null
For 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".
ariaControls
string | null
null
Id of the element this button controls. Pairs with ariaExpanded; point it at an element that is actually in the document.
ariaHasPopup
GogAriaHasPopup | null
null
boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' — what kind of popup the button opens.
ariaCurrent21.15.0
GogAriaCurrent | null
null
Marks 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.
ripple
boolean | undefined
undefined
Press 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
Name
Payload
Description
gogClick
MouseEvent
Emitted on each accepted click — after debounce throttling, and never while loading.
[gogButton] — Inputs
Name
Type
Default
Description
variant
'primary' | 'secondary' | 'outline' | 'ghost'
'primary'
Visual style — the same four the component offers.
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.
fullWidth
boolean
false
Stretches 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.
The 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-scale
How far a press shrinks the button. Dropped under prefers-reduced-motion, where the press colour carries the state on its own.
The 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.