Button

Overview

Use a native button for an immediate action. NeuButton adds signal inputs for tone, visual variant, size, loading and icon placement while retaining native button semantics. Use a link for navigation and a selection control for persistent choices; this component does not own form or selection state.

Basic interaction

Import Button and handle neuClick to run an action. Try the button, then open Source to copy the complete example.

States and variants

Use tone for semantic color: neutral, success, info, warning or danger. brand remains available for the primary action. All six tones support solid, outline and ghost variants. size changes the control dimensions. Loading disables activation and announces busy state.

Sizes and widths

size chooses sm, md or lg control dimensions; it is not a width input. A normal Button fits its content. fullWidth=true makes it occupy the containing surface.

For a fixed or responsive application width, use CSS such as inline-size: min(100%, 240px). There is no width input to bind. iconOnly uses square dimensions based on size; keep that mode separate from a full-width text action.

<button neu-button>Fit content</button>
<button neu-button [fullWidth]="true">Fill container</button>
<button neu-button style="inline-size: min(100%, 240px)">CSS width</button>

Icons

Choose one of two integration paths: set the icon input to an application key resolved by provideNeuIconResolver, or place an icon component or SVG directly inside the button. Projection needs neither the icon input nor a Core resolver. Neural Icons is one option, not a requirement; Core remains independent of the icon library.

For the icon input, iconPosition selects start or end. For projected content, put the icon before or after the text in the template. The add key also has a minimal Button fallback that works without a resolver; other application keys need a resolver and do not automatically load an icon catalog.

For an icon-only action, use iconOnly with either integration path, omit visible text and provide ariaLabel. iconOnly sets square dimensions; it does not remove projected content. The demo covers these options, and its TypeScript, HTML and provider tabs contain the code that runs them.

Icon contract

Configure Button

Change appearance, text, icon, width and interaction state, then copy the component code. The result uses the same values as the generated template. Click the enabled button to see its neuClick event count.

Width choices distinguish the Core fullWidth input from a CSS inline-size. Application icons also show the provider setup they need; Add can use the built-in fallback without that setup.

<button neu-button>Save changes</button>

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { NeuButtonComponent } from '@neural-ui/core/button';

@Component({
  selector: 'app-configured-button',
  standalone: true,
  imports: [NeuButtonComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <button
      neu-button
      [variant]="config.variant"
      [size]="config.size"
      [tone]="config.tone"
      [disabled]="config.disabled"
      [loading]="config.loading"
      [fullWidth]="config.fullWidth"
      [iconOnly]="config.iconOnly"
      [iconPosition]="config.iconPosition"
      [icon]="config.icon"
      [style.inline-size]="config.cssWidth === null ? null : 'min(100%, ' + config.cssWidth + 'px)'"
      [ariaLabel]="config.ariaLabel"
      (neuClick)="clicks.update(increment)"
    >
      {{ config.iconOnly ? '' : config.content }}
    </button>
    <output aria-live="polite">Interactions: {{ clicks() }}</output>
  `,
})
export class ConfiguredButton {
  readonly config = {
    "variant": "solid",
    "size": "md",
    "tone": "brand",
    "disabled": false,
    "loading": false,
    "fullWidth": false,
    "iconOnly": false,
    "iconPosition": "start",
    "icon": null,
    "content": "Save changes",
    "ariaLabel": "Save changes",
    "cssWidth": null
  } as const;
  readonly clicks = signal(0);
  readonly increment = (count: number) => count + 1;
}

Accessibility and keyboard

Core handles native keyboard activation, disabled/loading behavior and the busy-state attribute.

Your application supplies a clear action label. For an icon-only button, set ariaLabel. Keep decorative projected icons hidden from assistive technology.

API

Inputs configure applied state: use [property]="value" for a dynamic value or a literal attribute for a fixed string. Button has ten inputs and no editable value model. Its visible text is projected between the opening and closing button tags; there is no label input.

The neuClick output emits a MouseEvent when an enabled button is activated. Listen with (neuClick)="save($event)". Neither disabled nor loading is managed by that event; your application owns the operation and passes the current state back to Button.

Inputs

Configure the component with [property]="value". Your application supplies these values; the component does not replace the state you pass in.

Outputs

Listen to an event with (event)="handler($event)". The table explains the data your handler receives and how to use it.

Public Types

Open a type to inspect its definition and interface fields.

import type { NeuButtonIconPosition } from '@neural-ui/core/button';

// Public declaration (reference only)
export type NeuButtonIconPosition = 'start' | 'end';

import type { NeuButtonSize } from '@neural-ui/core/button';

// Public declaration (reference only)
export type NeuButtonSize = 'sm' | 'md' | 'lg';

import type { NeuButtonTone } from '@neural-ui/core/button';

// Public declaration (reference only)
export type NeuButtonTone = 'neutral' | 'brand' | 'success' | 'info' | 'warning' | 'danger';

import type { NeuButtonVariant } from '@neural-ui/core/button';

// Public declaration (reference only)
export type NeuButtonVariant = 'solid' | 'outline' | 'ghost';

Theming

Use the public --neu-button-* component tokens below, or a reusable preset from the Themes guide. Scope overrides to the application surface you want to customize.

Related components

Button group is the layout-only companion; it does not add selection state to Button.

• ButtonGroup