Feedback

Stable - @kikita-labs/ui v2.0.0

Loader

Directive for applying Kikita UI loading indicator styling to an inline element.

Import

Import the public directive from the published package entrypoint.

loader.ts
import { KuiLoader } from '@kikita-labs/ui';

Usage

Open in Playground

Apply kuiLoader to an inline element such as a span. The directive sets role="status" and aria-live="polite" so assistive technology announces the label.

<div class="loader-example">
  <span kuiLoader label="Loading"></span>
</div>

Sizes

Use the shared Kikita size scale to match the loader to the surrounding control or text.

<div class="loader-size-example">
  <span kuiLoader size="xs" label="Loading extra small"></span>
  <span kuiLoader size="sm" label="Loading small"></span>
  <span kuiLoader size="md" label="Loading medium"></span>
  <span kuiLoader size="lg" label="Loading large"></span>
</div>

With Button

kuiButton's own loading input (0.3.0) renders a kuiLoader internally, sets aria-busy="true", and behaves like disabled. Compose kuiLoader manually only when the button markup needs a custom saving label; otherwise prefer loading. A loading button keeps full opacity, and a kuiLoader inside a button takes the button text colour.

<div class="loader-button-example">
  <button kuiButton type="button" disabled>
    <span kuiLoader size="sm" label="Saving"></span>
    Saving
  </button>

  <button kuiButton type="button" loading>Saving</button>
</div>

Provider defaults

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

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

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        loader: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg' — Component size. Takes precedence over the global defaults.size.

Messages

Every text the component owns (accessible names, visible words, announcements) is a typed message with an English default. Override it for the application with provideKikitaUi({ messages }), or for a subtree with provideKuiMessages.

NameTypeDefaultDescription
clearstring — Accessible name of a clear action. Default Clear.
closestring — Accessible name of a close action. Default Close.
loadingstring — Accessible name of a busy indicator. Default Loading.
removestring — Accessible name of a remove action. Default Remove.

API

Inputs verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
size'xs' | 'sm' | 'md' | 'lg' | undefinedundefinedLoader size. Falls back to defaults.loader.size, then the global defaults.size, then md.
labelstring | undefinedundefinedAccessible label rendered as aria-label and announced through the host role="status" and aria-live="polite". Falls back to the common.loading message (Loading).
--kui-loader-sizeCSS custom property-Overrides the rendered loader diameter for the current size step.
--kui-loader-trackCSS custom property-Overrides the loader track (background ring) color.
--kui-loader-fillCSS custom property-Overrides the loader spinning fill color.
--kui-loader-border-widthCSS custom property-Overrides the loader ring stroke width.
--kui-loader-durationCSS custom property-Overrides the spin animation duration.
--kui-loader-duration-reducedCSS custom property-Spin animation duration used when the user prefers reduced motion.
KuiLoaderOptionsinterface-Shape of defaults.loader: size.

Accessibility

Loader announces progress through a live region instead of relying on visual motion alone.

  • The host element gets role="status" and aria-live="polite" automatically; no extra ARIA wiring is required.
  • label sets the accessible name via aria-label and defaults to the common.loading message (Loading), so it follows the active locale. Provide a specific label (for example Saving) whenever the loading context is not obvious from surrounding text.
  • Since 0.3.0, the loader keeps flex-shrink: 0 so it no longer collapses into an oval when its flex container shrinks it, such as inside a wrapped multi-line button label.
  • When composed inside a kuiButton with native disabled, the button itself communicates the busy state to assistive technology; keep disabled set for the duration of the loading state.

Migrating to 2.0

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

  • The directive class is KuiLoader; the Directive suffix is gone.
  • The default size moved to provideKuiDefaults({ loader: { size } }).
  • The default label now comes from the common.loading message, so it follows provideKuiLocale and provideKuiMessages; an unset label is undefined.
  • --kui-loader-duration-reduced sets the spin duration under reduced motion.
  • A loading Button keeps full opacity, and a kuiLoader placed inside a Button takes the button text colour.