Component v1.1.0 Foundations

Button

Action button with variants, sizes, disabled state, and loading feedback.

API Stable 2.1 WCAG notes Ready Dark mode
Selector
ui-button
Package
@ngnova/ui/button

Import

Standalone Tailwind v4
import { UiButtonComponent, UiButtonDirective, UiButtonGroupComponent, UiButtonIconDirective, UiButtonIconStartDirective, UiButtonIconEndDirective } from '@ngnova/ui/button';

Usage & variants

Live examples use the public ui-button API, paired with the exact snippet a product team would paste into an Angular app.

API Reference

Variants

Use visual weight to separate primary, secondary, quiet, and destructive actions.

Intent and appearance matrix

Review every semantic intent across every appearance; either input can also be used independently.

solid

outline

ghost

text

tonal

Sizes

Match button density to the surrounding surface without changing the component API.

Small · 30px
Medium · 36px
Large · 42px

States

Show pending work, disabled actions, and full-width mobile layouts explicitly.

Icons

Use the dedicated icon marker for square actions; size controls both the button and glyph.

Small · 30px
Medium · 36px
Large · 42px
Native

Links

Use uiButton on anchors and router links for navigation, including disabled-link semantics.

Group

Group related actions with connected edges, shared semantics, and unclipped keyboard focus.

Form submission

Set type="submit" deliberately; ui-button defaults to type="button" to prevent accidental submissions.

Form submissions: 0

Semantic events

Use pressed for activation and focused or blurred for focus-aware workflows.

Presses: 0 · Ready

Production guidance

Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.

When to use

Use intent for semantic color and appearance for visual treatment; variant remains supported for existing simple buttons.

Watch for

Disabled and loading buttons do not emit pressed.

Product recipes

Apply Button in distinct, copyable product scenarios—not just an isolated component state.

Release footer

A page footer with safe, secondary, and primary actions.

Angular template ui-button-recipe.example.html
1
2
3
4
5
6
7
<div class="flex flex-wrap justify-end gap-2">
  <ui-button variant="outline" (pressed)="cancel()">Cancel</ui-button>
  <ui-button variant="secondary" (pressed)="saveDraft()">Save draft</ui-button>
  <ui-button [loading]="publishing" loadingLabel="Publishing release" (pressed)="publish()">
    Publish
  </ui-button>
</div>

Icon action

Pair a short action label with a decorative icon, or provide an accessible label for an icon-only control.

Angular template ui-button-recipe.example.html
1
2
3
4
5
6
7
8
<ui-button (pressed)="createRelease()">
  <ng-icon uiButtonIconStart name="heroPlus" />
  Create release
</ui-button>

<ui-button iconOnly appearance="ghost" ariaLabel="More release actions">
  <ng-icon uiButtonIcon name="heroEllipsisHorizontal" />
</ui-button>

API Reference

Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.

Inputs

variant 'primary'
'primary' | 'secondary' | 'outline' | 'ghost' | 'danger'

Legacy visual emphasis style. Prefer intent and appearance for new combinations; either modern input takes precedence when supplied.

intent null
'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral' | null

Semantic color intent used with appearance.

appearance null
'solid' | 'outline' | 'ghost' | 'text' | 'tonal' | null

Visual treatment used with intent.

size 'md'
'sm' | 'md' | 'lg'

Button height and text scale.

disabled false
boolean

Disables pointer and keyboard activation.

loading false
boolean

Shows a spinner and disables activation.

fullWidth false
boolean

Expands the button to the full width of its container.

iconOnly false
boolean

Applies square sizing for icon-only buttons and suppresses full-width expansion.

[uiButton] iconOnly false
boolean

Applies square icon-button sizing to a native button, anchor, or router link.

ariaLabel ''
string

Accessible label for icon-only or visually ambiguous buttons.

loadingLabel 'Loading'
string

Screen-reader text announced while loading.

type 'button'
'button' | 'submit' | 'reset'

Native button type.

uiButton n/a
directive

Applies button styling and disabled-anchor handling to native buttons, anchors, and router links.

[uiButton] variant 'primary'
'primary' | 'secondary' | 'outline' | 'ghost' | 'danger'

Visual style for native buttons, anchors, and router links.

[uiButton] size 'md'
'sm' | 'md' | 'lg'

Height, padding, and text scale for the directive host.

[uiButton] disabled false
boolean

Disables native buttons and prevents disabled anchors or router links from activating.

[uiButton] fullWidth false
boolean

Expands the directive host to the full width of its container.

uiButtonIcon n/a
directive

Marks and normalizes the decorative glyph inside an icon-only button.

uiButtonIconStart n/a
directive

Marks a decorative leading icon and removes it from the accessibility tree.

uiButtonIconEnd n/a
directive

Marks a decorative trailing icon and removes it from the accessibility tree.

ui-button-group ariaLabel ''
string

Accessible label for a grouped set of related buttons.

ui-button-group fullWidth false
boolean

Stretches grouped buttons across the available width.

Outputs

pressed OutputEmitterRef<MouseEvent>

Emits when the enabled button is clicked or activated.

focused OutputEmitterRef<FocusEvent>

Emits when the native button receives focus. The host also forwards a native focus event.

blurred OutputEmitterRef<FocusEvent>

Emits when the native button loses focus. The host also forwards a native blur event.

Accessibility

  • UiButtonComponent renders a native button, so Enter and Space activation and disabled semantics remain predictable.
  • Icon-only buttons must provide ariaLabel; uiButtonIconStart and uiButtonIconEnd mark decorative icons aria-hidden.
  • The loading state sets aria-busy, includes loadingLabel for screen readers, and disables repeated activation.
  • Disabled anchors and router links receive aria-disabled="true", leave the tab order, and cannot navigate.
  • ui-button-group renders role="group" and should include ariaLabel when grouping related controls.
  • Grouped buttons preserve the standard outer focus-visible ring without clipping it at the group boundary.

Keyboard behavior

  • Enter and Space activate the native button.
  • Tab moves focus to enabled buttons.

Testing guidance

  • Import UiButtonHarness from @ngnova/ui/testing and filter with UiButtonHarness.with({ text }).
  • The harness supports click(), getText(), isDisabled(), isLoading(), and getType().
  • Verify pressed emits only when enabled, loading prevents repeat activation, and focus changes remain observable.
  • Cover accessible names for icon-only actions, disabled link behavior, and labels for grouped controls.