Button
Action button with variants, sizes, disabled state, and loading feedback.
- Selector
- ui-button
- Package
- @ngnova/ui/button
Import
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.
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.
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.
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.
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.
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.
| Name | Type | Default | Description |
|---|---|---|---|
variant | 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger' | 'primary' | Legacy visual emphasis style. Prefer intent and appearance for new combinations; either modern input takes precedence when supplied. |
intent | 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral' | null | null | Semantic color intent used with appearance. |
appearance | 'solid' | 'outline' | 'ghost' | 'text' | 'tonal' | null | null | Visual treatment used with intent. |
size | 'sm' | 'md' | 'lg' | 'md' | Button height and text scale. |
disabled | boolean | false | Disables pointer and keyboard activation. |
loading | boolean | false | Shows a spinner and disables activation. |
fullWidth | boolean | false | Expands the button to the full width of its container. |
iconOnly | boolean | false | Applies square sizing for icon-only buttons and suppresses full-width expansion. |
[uiButton] iconOnly | boolean | false | 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 | string | 'Loading' | Screen-reader text announced while loading. |
type | 'button' | 'submit' | 'reset' | 'button' | Native button type. |
uiButton | directive | n/a | Applies button styling and disabled-anchor handling to native buttons, anchors, and router links. |
[uiButton] variant | 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger' | 'primary' | Visual style for native buttons, anchors, and router links. |
[uiButton] size | 'sm' | 'md' | 'lg' | 'md' | Height, padding, and text scale for the directive host. |
[uiButton] disabled | boolean | false | Disables native buttons and prevents disabled anchors or router links from activating. |
[uiButton] fullWidth | boolean | false | Expands the directive host to the full width of its container. |
uiButtonIcon | directive | n/a | Marks and normalizes the decorative glyph inside an icon-only button. |
uiButtonIconStart | directive | n/a | Marks a decorative leading icon and removes it from the accessibility tree. |
uiButtonIconEnd | directive | n/a | 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 | boolean | false | 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.
| Name | Type | Description |
|---|---|---|
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.