Actions

Stable - @kikita-labs/ui v2.0.0

Button

Directive for applying Kikita UI button styling to native button and anchor elements.

Import

Import the public directive from the published package entrypoint and the style entrypoint once in the application.

import {
  KuiButton,
  type KuiButtonAppearance,
  type KuiButtonShape,
  provideKuiDefaults,
} from '@kikita-labs/ui';

Usage

Open in Playground

Use native button semantics for commands and anchor semantics for navigation.

Button docs
<div class="button-example">
  <button kuiButton type="button">Save changes</button>
  <button kuiButton type="button" shape="soft">Cancel</button>
  <a kuiButton routerLink="/components/button">Button docs</a>
</div>

Shape and appearance

shape controls the surface treatment (solid/soft/outline/ghost); appearance controls semantic color (primary/danger/success/warning). The two axes combine freely. Without an explicit appearance, solid and soft use primary colors and outline and ghost use their neutral defaults.

<div class="button-appearance-example">
  <button kuiButton type="button">Solid</button>
  <button kuiButton type="button" shape="soft">Soft</button>
  <button kuiButton type="button" shape="outline">Outline</button>
  <button kuiButton type="button" shape="ghost">Ghost</button>
  <button kuiButton type="button" appearance="danger">Danger</button>
  <button kuiButton type="button" shape="outline" appearance="danger">Outline danger</button>
</div>

Sizes and states

Use the shared Kikita size scale, native disabled state, and the loading state for pending actions. A loading button keeps full opacity and its layout size while a spinner covers the content.

<div class="button-size-example">
  <button kuiButton type="button" size="xs">Extra small</button>
  <button kuiButton type="button" size="sm">Small</button>
  <button kuiButton type="button" size="md">Medium</button>
  <button kuiButton type="button" size="lg">Large</button>
  <button kuiButton type="button" disabled>Disabled</button>
  <button kuiButton type="button" loading>Loading</button>
</div>

Icon composition

Use iconStart/iconEnd for a registered icon name instead of hand-projecting kui-icon. Icon-only actions use kuiIconButton's icon input the same way.

<div class="button-icon-example">
  <button kuiButton shape="soft" appearance="success" iconStart="check" type="button">Save</button>
  <button kuiButton shape="outline" iconEnd="arrow-right" type="button">Continue</button>
  <button
    kuiIconButton
    shape="soft"
    appearance="danger"
    icon="trash-2"
    aria-label="Delete"
    type="button"
  ></button>
</div>

Project kui-icon directly when the icon needs source or src instead of a registered name.

save-button.html
<button kuiButton appearance="success">
  <kui-icon [source]="checkIcon" />
  Save
</button>

Wrapping and links

Long labels truncate by default; wrap lets them use several lines. An anchor host is for navigation, and a disabled anchor leaves the tab order and suppresses navigation.

<div class="button-wrap-example">
  <button kuiButton type="button">Save changes and continue to the review step</button>
  <button kuiButton type="button" wrap>Save changes and continue to the review step</button>
</div>
Open the Button pageDisabled link
<div class="button-link-example">
  <a kuiButton shape="outline" routerLink="/components/button">Open the Button page</a>
  <a kuiButton shape="outline" routerLink="/components/button" disabled>Disabled link</a>
</div>

Provider defaults

Set defaults.button once for the application or for a subtree. Each option resolves as local input > defaults.button.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        button: {
          /* options below */
        },
      },
    }),
  ],
};
feature.providers.ts
import { provideKuiDefaults } from '@kikita-labs/ui';

export const featureProviders = [
  provideKuiDefaults({
    button: { shape: 'ghost', appearance: 'primary', size: 'sm' },
    iconButton: { shape: 'outline', size: 'sm' },
  }),
];

Resolution order, highest priority first:

  • the local input;
  • defaults.button (or defaults.iconButton);
  • the global defaults.size, for the size only;
  • the component default.

kuiButton and kuiIconButton are configured through separate button and iconButton keys, so one never restyles the other. A nested provider merges with its parent per property.

NameTypeDefaultDescription
shape'solid' | 'soft' | 'outline' | 'ghost' — Default surface shape.
appearance'primary' | 'danger' | 'success' | 'warning' | null — Default semantic color intent. Use null for each shape's neutral/default appearance.
size'xs' | 'sm' | 'md' | 'lg' — Default button size. Takes precedence over the global defaults.size.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-btn-solid-bg / -bg-hov / -bg-actCSS custom property-Fill, hover and active fill of the default and primary appearances.
--kui-btn-solid-fgCSS custom property-Label color of the default, primary, success and warning appearances.
--kui-btn-danger-bg / -bg-hov / -bg-actCSS custom property-Fill, hover and active fill of the danger appearance.
--kui-btn-danger-fgCSS custom property-Label color of the solid danger appearance.
--kui-btn-success-bg / -bg-hov / -bg-actCSS custom property-Fill, hover and active fill of the success appearance.
--kui-btn-warning-bg / -bg-hov / -bg-actCSS custom property-Fill, hover and active fill of the warning appearance.
--kui-btn-soft-* / --kui-btn-outline-* / --kui-btn-ghost-*CSS custom property-Surface tokens of the soft, outline and ghost shapes for the default appearance. Status appearances read the matching --kui-color-<status>-soft-* semantic tokens.
NameTypeDefaultDescription
--kui-btn-height-xsCSS custom property--kui-control-height-xsHeight, xs
--kui-btn-padding-inline-xsCSS custom property--kui-space-2Padding, inline xs
--kui-btn-height-smCSS custom property--kui-control-height-smHeight, sm
--kui-btn-padding-inline-smCSS custom property--kui-space-3Padding, inline sm
--kui-btn-height-lgCSS custom property--kui-control-height-lgHeight, lg
--kui-btn-padding-inline-lgCSS custom property--kui-space-5Padding, inline lg

API

Inputs, provider defaults and theming tokens verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
shape'solid' | 'soft' | 'outline' | 'ghost''solid'Surface treatment. Combines freely with appearance.
appearance'primary' | 'danger' | 'success' | 'warning' | nullnullSemantic color intent. Without an explicit value, solid and soft use primary colors and outline and ghost use their neutral defaults.
size'xs' | 'sm' | 'md' | 'lg''md'Control height and spacing size. Falls back to defaults.button.size, then the global defaults.size.
wrapbooleanfalseAllows long button text to wrap instead of truncating in narrow containers.
disabledbooleanfalseDisables button behavior. A button host gets the native disabled attribute; an anchor host gets aria-disabled="true", leaves the tab order and suppresses navigation.
loadingbooleanfalseCenters a kuiLoader spinner over the button content, fades the content out while keeping its layout size, sets aria-busy="true" and behaves like disabled. The button keeps full opacity instead of dimming like a disabled one.
iconStartKuiIconName | undefinedundefinedRenders a kui-icon resolved by registered name before the projected content, without hand-projecting kui-icon.
iconEndKuiIconName | undefinedundefinedRenders a kui-icon resolved by registered name after the projected content, without hand-projecting kui-icon.
provideKuiDefaults({ button })(defaults: KuiComponentDefaults) => Provider-Scopes repeated defaults for kuiButton in a component, route or feature subtree. A nested level merges with its parent per property. Use the defaults option of provideKikitaUi for the whole application.
KuiButtonOptionsinterface-Shape of defaults.button: shape, appearance (null selects each shape neutral appearance) and size. It is the same shape as KuiButtonBaseOptions, shared with defaults.iconButton.
KuiDefaultsservice-Injectable that reads and writes defaults at runtime: get(key) returns a Signal of the effective options, set and update write to the nearest level.
KuiButtonShape / KuiButtonAppearancetype aliases-Public unions of the shape and appearance values, exported for typed wrappers.
kuiProvideButtonOptionsdeprecated function-Forwards { button, iconButton } (KuiButtonProviderOptions) to provideKuiDefaults. Deprecated, removed in 3.0; use provideKuiDefaults.

Accessibility

Button keeps native element behavior instead of replacing it with ARIA roles.

  • Use <button> for in-page commands and form actions.
  • Use <a> only for real navigation with an href.
  • Every button needs an accessible name. Prefer visible text labels; icon-only actions should use kuiIconButton with an aria-label.
  • Native keyboard behavior is preserved: Enter and Space activate a button, links use native anchor behavior. The directive adds no custom keyboard model.
  • A disabled button uses the native disabled attribute. A disabled anchor gets aria-disabled="true", is removed from the tab order and suppresses navigation.
  • loading keeps the button's original content in layout, centers a spinner over it, sets aria-busy="true", and behaves like disabled until it clears.
  • Focus is a solid 2px outline in --kui-color-focus; no ring depends on box-shadow.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for buttons.

  • The class is KuiButton (it was KuiButtonDirective); the selector, inputs and class names are unchanged. ng update @kikita-labs/ui renames the import.
  • Defaults moved to provideKuiDefaults and defaults.button. The KUI_BUTTON_OPTIONS token is removed and kuiProvideButtonOptions is deprecated until 3.0. A nested provider now merges with its parent per property.
  • KuiButtonOptions describes one button. The old shape with button and iconButton keys is KuiButtonProviderOptions (deprecated).
  • The compatibility tokens --kui-btn-bg, --kui-btn-color and their siblings are no longer generated. Override the canonical --kui-btn-solid-* and --kui-btn-soft-* tokens, or the per-appearance tokens above.
  • Disabled buttons dim to the shared --kui-opacity-disabled (0.5), and a loading button no longer dims.
feature.providers.ts
// 1.x (deprecated, removed in 3.0)
providers: [kuiProvideButtonOptions({ button: { shape: 'ghost' } })];

// 2.0
providers: [provideKuiDefaults({ button: { shape: 'ghost' } })];