Progress

Overview

VyProgress displays determinate or indeterminate completion as a themed bar. It supports horizontal and vertical layouts, semantic colors, six sizes, percentage status text, reversed direction, animated indeterminate states, and an array-based stepped mode.

Usage

Bind a numeric value with v-model and set the maximum value.

Progress is a display component rather than an input. The binding is useful when application state changes the value; users do not directly edit it.

Status

Set status to show the rounded percentage above the bar.

Use the status slot to replace the default percentage text.

<template>
  <VyProgress :model-value="3" :max="8">
    <template #status="{ percent }">
      <text>{{ percent }}% · 3 of 8 files</text>
    </template>
  </VyProgress>
</template>

Indeterminate

Omit modelValue, or set it to null, when the amount of work is unknown.

The status and step labels are hidden while progress is indeterminate.

Steps

Pass an array to max to use its entries as step labels. The numeric value becomes the active zero-based step index, and the effective maximum is max.length - 1.

Each entry has a named step-N slot. By default, only the active step label is visible.

Vertical and inverted

A vertical progress bar needs an explicit height. inverted reverses the direction in either orientation.

Features and behavior

• A number renders determinate progress; null or undefined renders the indeterminate state.
• Numeric max defaults to 100 in the core primitive.
• An array max enables step labels and uses array.length - 1 as the numeric maximum.
• The displayed percentage is rounded to the nearest whole number and visually clamped from 0% to 100%.
• The core primitive validates determinate values. Values below 0, above max, or otherwise invalid are corrected to null, producing an indeterminate state.
• inverted reverses the indicator translation and status alignment.
• Horizontal progress fills the available width. Vertical progress fills the available height supplied by its parent.
• The indicator exposes data-state="indeterminate", "loading", or "complete" through the core primitive.

Props

Color defaults to primary, secondary, success, info, warning, error, or neutral, and supports registry extensions.

Emits

The component does not emit ordinary user interaction updates because it is non-interactive.

Slots

Styling and theming

Override globally through appConfig.ui.progress or locally with ui.

The theme combines color, size, orientation, inverted, animation, and an internal step state. Horizontal sizes range from 2px to 20px; vertical sizes use the same values as widths. Semantic color affects the indicator and step labels, while the track remains neutral.

Indeterminate animation utilities reference carousel, carousel-vertical, carousel-inverse, carousel-inverse-vertical, swing, swing-vertical, elastic, and elastic-vertical keyframes. The consuming app must provide the corresponding keyframes for animations it uses.

Accessibility

The core root is exposed as a native progress bar with the Lynx updating trait. Determinate values are announced as a rounded percentage of the maximum, such as “50%.” Indeterminate progress has no numeric accessibility value.

Place a visible label near the component so users know which task is progressing. The kit wrapper does not currently expose the core getValueLabel or getValueText callbacks; use ProgressRoot and ProgressIndicator from @vyui/core when the announced value must use application-specific wording such as “3 files.”

Do not rely on color alone to communicate completion, failure, or another task state. Pair the bar with text when that distinction matters.

Platform notes

• The kit provides a bar only. Circular progress based on inline SVG is not supported by Lynx native.
• Determinate fill is painted with a concrete translateX or translateY transform for consistent Lynx rendering.
• Lynx does not support fit-content for the status dimension, so the indeterminate fallback uses intrinsic auto sizing.
• Vertical layout requires a constrained parent height.
• Indeterminate motion depends on keyframes supplied by the consuming app; without them, the component remains visually indeterminate but static.

Related components

• Slider for a value users can change.
• Stepper for navigating an ordered sequence of interactive steps.
• Skeleton for placeholder content while its final shape is loading.
• The @vyui/core progress primitives for custom markup and accessible value text.