Progress

Linear progress indicator. Determinate (set width) or indeterminate (animated).

Overview

The Progress component is a core building block of the Byteion design system, providing a robust, accessibility-compliant interface for its specific UI capabilities.

Why this exists

Progress bars reduce user anxiety during waits. A visible progress indicator tells users that something is happening and roughly how much is left.

Mental model

A progress bar shows completion percentage (determinate) or activity without known duration (indeterminate). Use determinate when you know the total; use indeterminate when you don't.

When to use

• File upload progress • Form completion steps • Data loading or sync status • Multi-step onboarding

When not to use

• Do not use for quick actions (< 1 second) — a spinner is enough • Avoid for tasks with unknown progress — use indeterminate • Do not use fake progress — it erodes trust

Basic example

The following example demonstrates standard usage, fully compliant with Byteion's token-first approach.

Variants

Each variant communicates a different meaning. Choose based on priority, not aesthetics.

Single default variant.

Sizes

Size should match the importance and context of the component.

  • sm — sm size.
  • md — md size.
  • lg — lg size.

States

This component reacts seamlessly to the following interaction and data states:

  • indeterminate — Checkbox shows partial selection (parent/child).
  • default — Resting appearance before interaction.
  • hover — Pointer is over the element — visual feedback via color or shadow.
  • focus — Keyboard or tab focus — shows ring indicator for accessibility.
  • active — Currently selected or in use.
  • disabled — Non-interactive — grayed out, cursor not-allowed.

Anatomy

• Track — background bar • Fill — colored progress portion • Label — optional percentage or status text

Usage guidelines

  • Use determinate when you can measure progress.
  • Use indeterminate for unknown duration.
  • Show percentage for determinate.

Do and Don't

Do

  • Be honest about progress.
  • Show percentage for determinate.
  • Use indeterminate for unknown waits.

Don't

  • Do not fake progress percentages.
  • Do not use determinate for unknown waits.
  • Do not hide the progress bar during the task.

Accessibility

Uses role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax.

Role:progressbar

Customization

Fill color follows semantic tokens.

Compose with React cva()

Use the exportedcva() +cn() utilities to compose your own variant on top of the Byteion tokens.

import { cva, cn, type VariantProps } from '@byteion/react';

const myProgress = cva('base classes…', {
 variants: {
  accent: { soft:'border-primary-200', loud:'border-primary-500' },
 },
 defaultVariants: { accent:'soft' },
});

type Props = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof myProgress>;

Compose with Vue cva()

Use the exportedcva() +cn() utilities inside standard Vue setup blocks.

<script setup lang="ts">
import { computed, useAttrs } from 'vue';
import { cva, type VariantProps } from '@byteion/vue';

interface Props { accent?:'soft' |'loud' }
const props = withDefaults(defineProps<Props>(), { accent:'soft' });
const attrs = useAttrs();

const myProgress = cva('base classes…', {
  variants: { accent: { soft:'border-primary-200', loud:'border-primary-500' } },
});

const cls = computed(() => myProgress({ accent: props.accent, class: attrs.class as string | undefined }));
</script>

Runtime events

Byteion keeps framework APIs idiomatic: HTML uses DOM custom events, React uses callback props, and Vue uses emitted events / v-model updates.

HTML / JS events

No HTML runtime events are declared by this adapter.

React callbacks

No React callback events are declared by this adapter.

Vue emits

No Vue emitted events are declared by this adapter.

Remote / AJAX

This component does not implement Byteion JS remote loading. Use normal HTML form submission, framework state, or your application data layer around it.

API Reference

Static HTML. Update fill width via style or class.

HTML Data Attributes

No custom data attributes required.

React Props · ProgressProps

Extracted directly fromreact/src/components/Progress.tsx.

export interface ProgressProps
  extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>,
    VariantProps<typeof track>,
    VariantProps<typeof bar> {
  /** Current progress, 0 to `max`. Omit for indeterminate. */
  value?: number;
  /** Maximum value. Defaults to 100. */
  max?: number;
  /** Optional left label rendered above the track. */
  label?: ReactNode;
  /** Optional right label (e.g. "42 / 100 GB"). */
  valueLabel?: ReactNode;
  /** Show the value as a percent on the right when `valueLabel` is not given. */
  showPercent?: boolean;
}

React Variant Schema

Internal variant composition defined viacva().

cva('w-full overflow-hidden rounded-full bg-muted', {
  variants: {
    size: {
      sm: 'h-1',
      md: 'h-2',
      lg: 'h-3',
      xl: 'h-4',
    },
  },
  defaultVariants: { size: 'md' },
})

Vue Props · ProgressProps

Extracted directly fromvue/src/components/Progress.vue.

export interface ProgressProps {
  /** Current progress, 0 to `max`. Omit for indeterminate. */
  value?: number;
  /** Maximum value. Defaults to 100. */
  max?: number;
  size?: 'sm' | 'md' | 'lg' | 'xl';
  tone?: 'primary' | 'secondary' | 'accent' | 'success' | 'warning' | 'danger' | 'violet' | 'info';
  striped?: boolean;
  /** Optional left label rendered above the track. */
  label?: string;
  /** Optional right label (e.g. "42 / 100 GB"). */
  valueLabel?: string;
  /** Show the value as a percent on the right when `valueLabel` is not given. */
  showPercent?: boolean;
}

Developer tips

• Best practice: for uploads, show bytes transferred alongside the bar.

Common mistakes

Avoid hardcoded neutral colors, placeholder-only labels, duplicated primary actions, and missing keyboard states. Keep this component on Byteion tokens so dashboard, admin, POS, ERP, ecommerce back-office, Laravel, React, and Vue starter-kit screens can be rebranded without rewriting markup.

Production usage tips

Use the canonical HTML as the source of truth, keep React and Vue wrappers aligned with the documented variants, test dark mode and branded themes before release, and wire interactive behavior through data-bi-* attributes instead of styling hooks.

Premium examples

Advanced patterns available in Byteion Pro:

• Striped animated progress for indeterminate • Segmented progress for multi-step forms • Color transitions (danger → warning → success)

Related components

Unlock Premium Patterns

Get access to copy-paste ready Pro blocks, SaaS templates, and advanced data-tables built with this component.

Explore Pro Components