Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

Progress

A native progress element for determinate or indeterminate work.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add progress

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Progress from './components/ui/progress/Progress.vue'

const uploaded = ref(42)
</script>

<template>
  <Progress :value="uploaded" :max="100" aria-label="Upload progress" />
  <Progress :value="null" aria-label="Preparing upload" />
</template>

Omit value or pass null for indeterminate progress. Supply aria-label or aria-labelledby, and use aria-valuetext when the numeric value does not express the user-facing state.

When to use it

File transfer

Show known bytes transferred relative to total bytes.

Unknown-duration work

Show that a request is still running when completion cannot be measured.

More examples

Determinate upload

Use a numeric value and a visible text equivalent.

Determinate upload
<script setup lang="ts">
import { ref } from 'vue'
import Progress from './components/ui/progress/Progress.vue'

const uploaded = ref(64)
</script>

<template>
  <div>
    <p>Uploading files:&nbsp;{{ uploaded }}%</p>
    <Progress :value="uploaded" :max="100" aria-label="File upload" />
  </div>
</template>

Preparing a report

Pass null until the job exposes a measurable total.

Preparing a report
<script setup lang="ts">
import Progress from './components/ui/progress/Progress.vue'
</script>

<template>
  <div>
    <p>Preparing report…</p>
    <Progress :value="null" aria-label="Preparing report" />
  </div>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Progress

Complete API for Progress
NameType or signatureDefaultWhat it does
valuepropnumber | null | undefinednullValue represented by this control or option.
maxpropnumber | undefined100Largest allowed value.
sizeprop"sm" | "md" | "lg" | undefined"md"Choose the visual size. Medium is the usual default where available.
variantprop"default" | "success" | "warning" | "destructive" | undefined"default"Choose the visual treatment for this component.
elementexposedHTMLProgressElement | null—Reference to the underlying HTML element.
Public type definitions
Public types
// packages/frameworks/vue/components/progress/types.ts
// ------- IMPORTS -------

import type { progressSizes, progressVariants } from './styles'

// ------- TYPES -------

export interface ProgressProps {
  value?: number | null
  max?: number
  size?: keyof typeof progressSizes
  variant?: keyof typeof progressVariants
}


// packages/frameworks/vue/components/progress/styles.ts
// Change Progress track height and fill colors here; public visual types follow these keys.
export const progressSizes = { sm: 'h-1', md: 'h-2', lg: 'h-3' } as const

export const progressVariants = {
  default: '[&::-moz-progress-bar]:bg-primary [&::-webkit-progress-value]:bg-primary',
  success: '[&::-moz-progress-bar]:bg-success [&::-webkit-progress-value]:bg-success',
  warning:
    '[&::-moz-progress-bar]:bg-warning-indicator [&::-webkit-progress-value]:bg-warning-indicator',
  destructive: '[&::-moz-progress-bar]:bg-destructive [&::-webkit-progress-value]:bg-destructive',
} as const

Implementation notes

  • Clamp application values to their actual range before showing user-facing percentages.
  • Switch from indeterminate to determinate only when the denominator is known.

Accessibility and localization

  • Name every progress indicator; use aria-valuetext when a numeric value does not describe the stage.

Source contract and editing guidance