Actions

Stable - @kikita-labs/ui v1.6.1

Icon Button

Square icon-only action control for native buttons and links.

Import

Use the icon button directive on native button or anchor elements. Use its icon input for a registered icon name, or project kui-icon directly for source/src icons.

icon-button.ts
import { KuiIconButtonDirective, KuiIconComponent } from '@kikita-labs/ui';

Usage

Open in Playground

Icon-only controls must provide an accessible label on the host element.

<div class="icon-button-appearance-example">
  <button kuiIconButton type="button" aria-label="Add item">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="soft" aria-label="Add item softly">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="outline" aria-label="Add item with outline">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="ghost" aria-label="Add item quietly">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" appearance="danger" aria-label="Delete item">
    <kui-icon [source]="trashIcon" />
  </button>
  <button
    kuiIconButton
    type="button"
    shape="outline"
    appearance="danger"
    aria-label="Delete item with outline"
  >
    <kui-icon [source]="trashIcon" />
  </button>
</div>

Shape and appearance

shape controls the surface treatment (solid/soft/outline/ghost, default ghost); appearance controls semantic color (primary/danger/success/warning). The two axes combine freely.

<div class="icon-button-appearance-example">
  <button kuiIconButton type="button" aria-label="Add item">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="soft" aria-label="Add item softly">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="outline" aria-label="Add item with outline">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="ghost" aria-label="Add item quietly">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" appearance="danger" aria-label="Delete item">
    <kui-icon [source]="trashIcon" />
  </button>
  <button
    kuiIconButton
    type="button"
    shape="outline"
    appearance="danger"
    aria-label="Delete item with outline"
  >
    <kui-icon [source]="trashIcon" />
  </button>
</div>

Size

Size (data-kui-size) drives control height directly; data-kui-density no longer affects height. Default md matches kui-input at 40px. loading replaces the icon with a centered kui-loader spinner and behaves like disabled.

<div class="icon-button-size-example">
  <button kuiIconButton type="button" size="xs" aria-label="Extra small settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" size="sm" aria-label="Small settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" size="md" aria-label="Medium settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" size="lg" aria-label="Large settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" disabled aria-label="Disabled settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" loading aria-label="Loading settings">
    <kui-icon [source]="settingsIcon" />
  </button>
</div>

Icon composition

Use icon for a registered icon name instead of hand-projecting kui-icon.

<div class="icon-button-icon-example">
  <button kuiIconButton icon="plus" aria-label="Add item" type="button"></button>
  <button
    kuiIconButton
    shape="outline"
    appearance="danger"
    icon="trash-2"
    aria-label="Delete item"
    type="button"
  ></button>
  <button kuiIconButton shape="soft" icon="settings" aria-label="Settings" type="button"></button>
</div>

API

Inputs verified against @kikita-labs/ui v1.6.1 public typings.

NameTypeDefaultDescription
shape'solid' | 'soft' | 'outline' | 'ghost''ghost'Surface treatment. Defaults to ghost. Combines freely with appearance.
appearance'primary' | 'danger' | 'success' | 'warning' | nullnullSemantic color intent. Without an explicit value, solid/soft use primary colors and outline/ghost use neutral defaults.
size'xs' | 'sm' | 'md' | 'lg''md'Square control size mapped to Kikita control height tokens (matches kui-input height at md).
disabledbooleanfalseDisables native button behavior. Anchor icon buttons receive aria-disabled and leave tab order.
loadingbooleanfalseReplaces the icon (and any projected content) with a centered kui-loader spinner, sets aria-busy, and behaves like disabled.
iconKuiIconName | undefinedundefinedRenders a kui-icon resolved by name as the button content, prepended before any other projected content, without hand-projecting kui-icon.

Accessibility

The visual icon is decorative when the host already has a clear label.

  • Add aria-label to every icon-only button or link.
  • Keep icons decorative with no label on kui-icon.
  • Use native disabled for buttons and the directive-managed disabled state for anchors.
  • Prefer visible text buttons when the icon meaning is not widely understood.
  • loading sets aria-busy="true" and behaves like disabled until it clears.

Known gaps

Differences from the sibling Button API worth calling out.

  • Since 0.2.0, control height is driven only by size (data-kui-size). data-kui-density no longer changes icon button height.