Kappa / Loader

Processing payment...Please keep this window open.

$100.00

<script setup>
import { Loader } from "@dicehub/kappa/components/loader";
</script>

<template>
  <div class="payment-status" role="status" aria-live="polite">
    <Loader decorative size="lg" />
    <div>
      <strong>Processing payment...</strong>
      <span>Please keep this window open.</span>
    </div>
    <span>$100.00</span>
  </div>
</template>

Installation

Loader is part of the main Kappa package. It uses CSS motion and has no runtime dependency or state machine.

Barrel

import { Loader } from "@dicehub/kappa";

Granular

import { Loader } from "@dicehub/kappa/components/loader";

Usage

Loader announces a polite status with the text Loading by default. Setlabel to specific, translated text when the operation needs more context.

<script setup>
import { Loader } from "@dicehub/kappa/components/loader";
</script>

<template>
  <Loader />
</template>

The default Loader uses a compact two-circle form. Other variants provide distinct motion for technical states, dense controls, and larger waiting surfaces. Ark UI does not provide a Loader primitive; useArk UI Progress when a value or determinate range is available.

Every graphic inherits currentColor. Motion uses Kappa CSS keyframes and becomes a stable static shape when the user requests reduced motion.

Examples

Variants

Choose a motion that fits the available space and the character of the pending task. Keep one variant consistent within the same workflow.

Spinner

Waveform

Helix

Quantum

Dot wave

Dot stream

Mirage

Ping

Orbit

<Loader variant="spinner" />
<Loader variant="waveform" />
<Loader variant="helix" />
<Loader variant="quantum" />
<Loader variant="dot-wave" />
<Loader variant="dot-stream" />
<Loader variant="mirage" />
<Loader variant="ping" />
<Loader variant="orbit" />

Run Waiting

The orbit variant matches the established dicehub run-waiting indicator. Use a visible status message and make the graphic decorative to prevent duplicate announcements.

Waiting to start...Preparing resources for the run.

<div role="status" aria-busy="true" aria-live="polite">
  <Loader decorative :duration="900" :size="80" variant="orbit" />
  <div>
    <strong>Waiting to start...</strong>
    <span>Preparing resources for the run.</span>
  </div>
</div>

Sizes

Use small inline, base in ordinary surfaces, and large in prominent loading states.

Loading sm examplesm

Loading base examplebase

Loading lg examplelg

<Loader size="sm" label="Loading small example" />
<Loader size="base" label="Loading base example" />
<Loader size="lg" label="Loading large example" />

Custom Size

Pass a positive number when a composition needs a size outside the three presets.

Loading large preview40 px

<Loader :size="40" label="Loading large preview" />

Button

Keep the button label visible, set aria-busy on the affected control or region, and make the Loader decorative so assistive technology does not announce the same state twice.

<script setup>
import { Button } from "@dicehub/kappa/components/button";
import { Loader } from "@dicehub/kappa/components/loader";
</script>

<template>
  <div aria-busy="true">
    <Button disabled variant="primary">
      <Loader decorative data-icon="inline-start" size="sm" />
      Submitting
    </Button>
  </div>
</template>

Badge

Use current-color inheritance to keep the Loader legible in each Badge treatment.

SyncingUpdating Processing

<script setup>
import { Badge } from "@dicehub/kappa/components/badge";
import { Loader } from "@dicehub/kappa/components/loader";
</script>

<template>
  <Badge>
    <Loader decorative :size="12" data-icon="inline-start" />
    Syncing
  </Badge>
</template>

Empty

Use a decorative Loader when the Empty title and description provide the status text.

<script setup>
import { Button } from "@dicehub/kappa/components/button";
import { Empty } from "@dicehub/kappa/components/empty";
import { Loader } from "@dicehub/kappa/components/loader";
</script>

<template>
  <Empty.Root size="sm">
    <Empty.Header>
      <Empty.Media><Loader decorative size="lg" /></Empty.Media>
      <Empty.Title>Processing your request</Empty.Title>
      <Empty.Description>
        Please wait while the request completes. Do not refresh this page.
      </Empty.Description>
    </Empty.Header>
    <Empty.Content><Button size="sm" variant="outline">Cancel</Button></Empty.Content>
  </Empty.Root>
</template>

Accessibility

The default Loader is a polite status with real visually hidden text.
Use a short, translated label that describes the operation.
Set decorative when nearby visible text already reports the same state.
Put aria-busy="true" on the region or control whose update is pending.
Do not use Loader for known progress. Use a progress indicator with a value instead.
Reduced-motion mode removes Loader animations and keeps a static loading shape.

API Reference

Loader

Renders a span and forwards native attributes and listeners to it.

Prop	Type	Default	Description
`size`	`"sm" \| "base" \| "lg" \| number`	`"base"`	Sets a 16, 24, or 32 pixel preset, or a custom positive pixel size.
`variant`	`"spinner" \| "waveform" \| "helix" \| "quantum" \| "dot-wave" \| "dot-stream" \| "mirage" \| "ping" \| "orbit"`	`"spinner"`	Selects the loading motion.
`duration`	`number`	`1500`	Sets the animation cycle in milliseconds. Values are limited to 400–10,000 ms.
`label`	`string`	`"Loading"`	Sets the visually hidden status text. Translate it for the current locale.
`decorative`	`boolean`	`false`	Removes status semantics when nearby visible text already describes the state.

Exports

Export	Description
`Loader`	Loading status component with several motion variants.
`LoaderProps`	Public Loader prop contract.
`LoaderSize / LoaderVariant`	Supported size and motion names.
`LOADER_SIZES / LOADER_VARIANTS`	Stable preset collections.
`LOADER_DEFAULT_*`	Default size, variant, duration, and status text.
`LOADER_DEFAULT_LABEL`	Default status text.
`isLoader*`	Runtime guards for preset values.
`resolveLoader*`	Safe runtime resolvers for public props.