Kappa / Matrix Loader

GEOMETRY PIPELINEIndexing surface cellsPreparing the model for refinement.48,216cells

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

<template>
  <div role="status" aria-busy="true" aria-live="polite">
    <MatrixLoader decorative motion="orbit" shape="ring" size="lg" />
    <div>
      <strong>Indexing surface cells</strong>
      <span>Preparing the model for refinement.</span>
    </div>
  </div>
</template>

Installation

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

Barrel

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

Granular

import { MatrixLoader } from "@dicehub/kappa/components/matrix-loader";

Usage

Use Matrix Loader for compact technical states that benefit from more visual presence than a circular spinner. Use label to describe the active operation.

Indexing surface cells

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

<template>
  <MatrixLoader label="Indexing surface cells" />
</template>

Design

Shape and motion are independent. Every option uses the same five-by-five matrix, so changing the visual treatment does not change the component size or status semantics.

The dot phases are deterministic. Server rendering, hydration, tests, and repeated loaders therefore produce stable output without random values.

Examples

Shapes

Square, circle, diamond, and ring shapes select different positions in the same matrix.

Square

Circle

Diamond

Ring

<MatrixLoader shape="square" motion="pulse" />
<MatrixLoader shape="circle" motion="pulse" />
<MatrixLoader shape="diamond" motion="pulse" />
<MatrixLoader shape="ring" motion="pulse" />

Motion Patterns

Pulse expands from the center, scan crosses columns, twinkle uses a fixed irregular order, and orbit follows the field angle.

Pulse

Scan

Twinkle

Orbit

<MatrixLoader motion="pulse" shape="circle" />
<MatrixLoader motion="scan" shape="circle" />
<MatrixLoader motion="twinkle" shape="circle" />
<MatrixLoader motion="orbit" shape="circle" />

Sizes

Use the same compact size scale as Loader, or pass a positive pixel value.

Small

Base

Large

<MatrixLoader size="sm" />
<MatrixLoader size="base" />
<MatrixLoader size="lg" />
<MatrixLoader :size="48" />

Cycle Duration

Change the duration when the surrounding interface needs a faster or calmer loading signal.

Fast

Measured

<MatrixLoader :duration="800" motion="scan" shape="diamond" />
<MatrixLoader :duration="1800" motion="scan" shape="diamond" />

Accessibility

The default component is a polite status with visually hidden text.
Use a short, translated label that identifies the active operation.
Set decorative when nearby visible text already reports the same state.
Set aria-busy="true" on the region or control that is updating.
Use Progress instead when the application knows the completion value.
Reduced-motion mode stops every dot and keeps the selected shape visible.

API Reference

MatrixLoader

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

Prop	Type	Default	Description
`size`	`"sm" \| "base" \| "lg" \| number`	`"base"`	Sets a preset size or an exact positive pixel size.
`shape`	`"square" \| "circle" \| "diamond" \| "ring"`	`"square"`	Selects which positions in the five-by-five matrix are visible.
`motion`	`"pulse" \| "scan" \| "twinkle" \| "orbit"`	`"pulse"`	Selects the phase sequence used by the visible dots.
`duration`	`number`	`1200`	Sets the animation cycle in milliseconds. Values are limited to 400–10,000 ms.
`label`	`string`	`"Loading"`	Provides the visually hidden status announced by assistive technology.
`decorative`	`boolean`	`false`	Hides the loader when nearby visible text already reports the loading state.

Exports

Export	Description
`MatrixLoader`	Dot-matrix loading status component.
`MatrixLoaderProps`	Public MatrixLoader prop contract.
`MatrixLoaderSize / Shape / Motion`	Supported visual option types.
`MATRIX_LOADER_SIZES / SHAPES / MOTIONS`	Stable preset collections.
`MATRIX_LOADER_DEFAULT_*`	Default size, shape, motion, duration, and label values.
`resolveMatrixLoader*`	Safe runtime resolvers for public prop values.