Kappa / Progress

Uploading simulation results68%

<script setup>
import { Progress } from "@dicehub/kappa/components/progress";
</script>

<template>
  <Progress.Root :default-value="68">
    <Progress.Label>Uploading simulation results</Progress.Label>
    <Progress.ValueText />
    <Progress.Track aria-label="Uploading simulation results">
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

Installation

Progress is part of the main Kappa package. Ark UI owns its value machine and progressbar semantics.

Barrel

import {
  Progress,
  ProgressLabel,
  ProgressRange,
  ProgressRoot,
  ProgressTrack,
  ProgressValueText,
} from "@dicehub/kappa";

Granular

import {
  Progress,
  ProgressLabel,
  ProgressRange,
  ProgressRoot,
  ProgressTrack,
  ProgressValueText,
} from "@dicehub/kappa/components/progress";

Usage

Use Progress for task completion, loading, or a process with a known end. Use Meter for a scalar measurement such as capacity or storage.

Uploading simulation results68%

<script setup>
import { Progress } from "@dicehub/kappa/components/progress";
</script>

<template>
  <Progress.Root :default-value="68">
    <Progress.Label>Uploading simulation results</Progress.Label>
    <Progress.ValueText />
    <Progress.Track aria-label="Uploading simulation results">
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

Composition

Typical part hierarchy

Progress.Root
├── Progress.Label
├── Progress.ValueText
├── Progress.Track
│   └── Progress.Range
├── Progress.View (optional)
└── Progress.Context (optional)

Ark UI owns range calculation, controlled and uncontrolled values, state attributes, formatted values, and WAI-ARIA progressbar behavior. Kappa owns the linear anatomy, visual tokens, motion, and compound exports.

Root owns the value, range, locale, and loading state.
Track is the progressbar. Give it a concise accessible name.
Range shows determinate progress or the indeterminate motion.
ValueText uses the Ark percentage format unless its slot replaces it.

Examples

Custom Range

Use a numeric range that matches the task. Replace the visible value when counts are clearer than a percentage.

Result files5 / 8

<script setup>
import { Progress } from "@dicehub/kappa/components/progress";
</script>

<template>
  <Progress.Root :default-value="5" :min="0" :max="8">
    <Progress.Label>Result files</Progress.Label>
    <Progress.ValueText>5 / 8</Progress.ValueText>
    <Progress.Track aria-label="Result files">
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

Indeterminate

Set the value to null when the process has no reliable completion estimate.

Preparing meshWorking…

<script setup>
import { Progress } from "@dicehub/kappa/components/progress";
</script>

<template>
  <Progress.Root :model-value="null">
    <Progress.Label>Preparing mesh</Progress.Label>
    <Progress.ValueText>Working…</Progress.ValueText>
    <Progress.Track aria-label="Preparing mesh">
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>
</template>

Controlled

Use v-model when application state owns the current progress value.

Solver progress36%

Set progress

<script setup>
import { Progress } from "@dicehub/kappa/components/progress";
import { ref } from "vue";

const value = ref(36);
</script>

<template>
  <Progress.Root v-model="value">
    <Progress.Label>Solver progress</Progress.Label>
    <Progress.ValueText />
    <Progress.Track aria-label="Solver progress">
      <Progress.Range />
    </Progress.Track>
  </Progress.Root>

  <label>
    Set progress
    <input v-model.number="value" type="range" min="0" max="100" />
  </label>
</template>

Accessibility

Track exposes role=progressbar, its range, state, and current value.
Give the progressbar an accessible name that identifies the process.
A null value removes aria-valuenow and signals an indeterminate process.
Do not update a determinate value more often than users need. Excess announcements can be disruptive.
Reduced-motion preferences stop the indeterminate animation and value transition.

API Reference

Progress.Root

Prop	Type	Default	Description
`modelValue / defaultValue`	`number \| null`	`50`	Controlled value or initial value. Null selects the indeterminate state.
`min / max`	`number`	`0 / 100`	Numeric range used for value and percentage calculation.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Direction used by the Ark progress machine and range geometry.
`formatOptions`	`Intl.NumberFormatOptions`	`percent`	Formats the default ValueText output.
`locale`	`string`	`"en-US"`	Locale used to format the value.
`translations`	`IntlTranslations`	`Ark defaults`	Customizes the assistive value description.
`id / ids`	`string / partial ID map`	`generated`	Overrides the machine and part identifiers.
`asChild`	`boolean`	`false`	Merges root behavior into the direct child.

Parts

Part	Element	Description
`Progress.Label`	`label`	Visible progress label.
`Progress.ValueText`	`span`	Formatted value or custom status text.
`Progress.Track`	`div`	Progressbar element and complete range.
`Progress.Range`	`div`	Determinate fill or indeterminate indicator.
`Progress.View`	`div`	Content shown for loading, complete, or indeterminate state.
`Progress.Context`	`renderless`	Exposes the Ark progress context to a slot.

Events

Event	Payload	Description
`update:modelValue`	`number \| null`	Updates v-model when the Ark machine value changes.
`valueChange`	`ProgressValueChangeDetails`	Reports each value change.

Exports

Export	Description
`Progress`	Styled compound component with all linear parts.
`ProgressRoot / ProgressRootProvider`	Direct root and external-machine provider components.
`ProgressLabel / ProgressValueText / ProgressTrack / ProgressRange`	Granular styled linear parts.
`ProgressView / ProgressContext`	State view and renderless context parts.
`useProgress / useProgressContext`	Ark UI composition functions.
`ProgressProps / ProgressSlots / ProgressValueChangeDetails`	Public TypeScript contracts.