Skip to content
SkillCodex
Menu

Progress bar

Progress bar

A visual and semantic indicator for task completion: it exposes a value within a known range when measurable and remains indeterminate when no reliable value exists.

Try the component
Context, sources and actions
Sources and revision
Updated
Version
v1.0.26 · r2
Sources
5 sources
Status
Published
Read the sources

You may have searched for: show how much of the upload is donea bar filling from zero to one hundredtrack known progress during import

All phrasings
Save and share

Recognize

Wait and track progress

Try it

Is duration unknown, measurable, or should the content shape be preserved?

Progress bar

Shared trial context

A workspace waits for content or an operation to finish and communicates only the progress it can measure honestly.

Progress bar

Mission

Progress bar

Start the upload, observe a mid-progress value, cancel, restart, and reach the completed state.

0/20 MB, 0%

Live result

The upload has not started.

Step 1 of 3

Try

Try the component. Your live result appears just above. Move on at your own pace.

Behavior and edge case
What to observe
The labeled progress element exposes bytes and percentage while the file transfers.
Edge case
If the server stops providing reliable values, the UI switches honestly to an indeterminate busy state instead of faking progress.

What this example shows

Progress bar represents completion over a task and exposes a measured value when available; Spinner is a compact busy indicator, while Skeleton represents the eventual content layout.

Which fits your need?

Progress bar

Uploading a file with reliable byte progress

Spinner

A short operation has no meaningful completion value

Which component will you use here?
Difference and sources

Progress bar represents completion over a task and exposes a measured value when available; Spinner is a compact busy indicator, while Skeleton represents the eventual content layout.

Read the sources

    Parts of the specimen

    Select a numbered marker on the schematic, or use the list below, to see its role. The schematic shows the concept's representative state.

    Label

    The persistent text that names a control or field.

    Position in the atlas

    Relationship map

    Locate the chapter, neighboring concepts, and the next useful decision.

    • Chapter

      Wait and track progress

      Progress bar belongs to this comparison group.

    • Do not confuse

      Spinner

      Choose Progress bar if you know a reliable value, such as bytes sent or steps completed. Choose Spinner if the operation is short and has no meaningful completion value.

      Compare this pair
    • Do not confuse

      Skeleton

      Choose Progress bar if a task has a reliable completion value, such as an upload in bytes. Choose Skeleton if a page region loads content whose layout is known in advance.

      Compare this pair
    • Next step

      Compare the concepts in the chapter before choosing an implementation.

      Open the chapter

    In your own words

    Understand

    What people describe

    Documented aliases: completion bar, determinate progress, upload progress

    • show how much of the upload is done
    • a bar filling from zero to one hundred
    • track known progress during import
    • display sixty percent complete
    • a measurable installation status
    • show remaining progress without a spinner

    Choose

    Use it when

    • Uploading a file with reliable byte progress
    • Completing a known sequence of processing steps

    Avoid it when

    • The value is guessed or jumps unpredictably
    • Only the content shape, not completion, matters

    Compare

    Compare similar concepts

    Verification checklist

    Try these actions in the lab, then check the same behaviours in your agent’s result. Adapt the example names to your interface.

    1. 1. Do this

      Start an operation with measurable progress and compare the displayed value with its progress text.

      Expected result

      The value, range and operation label agree; a percentage represents actual progress rather than elapsed decoration.

    2. 2. Do this

      Use the separate cancel or restart control if offered, then let a run complete.

      Expected result

      Cancelled, running and completed states are distinguishable, and the bar itself does not become a keyboard stop.

    3. 3. Do this

      Try an operation whose total or remaining progress is unknown.

      Expected result

      The interface uses an honest indeterminate state instead of inventing a numerical value or claiming completion.

    Full contract
    1. 1Minimum, maximum, and current value are real
    2. 2A visible or accessible label names the operation
    3. 3Updates are understandable rather than noisy
    4. 4Completion, failure, and cancellation have final states

    Understand → Recognize → Choose → Compare

    Pack for your agent

    Pre-written instructions to paste into your agent. Copying executes nothing.

    Implement correctly

    Build Progress bar without breaking its behavior

    # Implement Progress bar in your agent
    
    ## Objective
    Implement Progress bar for this verified behavior: A visual and semantic indicator for task completion: it exposes a value within a known range when measurable and remains indeterminate when no reliable value exists.
    
    ## Prerequisites
    - Inspect the repository, design system, and existing tests first.
    - Preserve unrelated changes and keep the file scope bounded.
    - Confirm that Progress bar matches the need before writing code.
    
    ## Required behavior
    - The current value advances within a known minimum and maximum without excessive announcements.
    - The content region exposes its busy state while a separate visual indicator remains redundant.
    
    ## States to cover
    - Upload idle
    - Upload with measured progress
    - Upload without a reliable estimate
    - Upload cancelled
    - Upload complete
    
    ## Accessibility
    - ARIA role: progress
    - The primary control or named region for Progress bar has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    - The progress indicator does not receive focus; focus remains on the operation controls or current task.
    - It ends only on completion, failure, or explicit cancellation and is replaced by the matching final status.
    - The accessible name and current value are exposed; announcements are paced to avoid reading every tiny update.
    - Tab skips the noninteractive bar
    - Tab reaches a separate Cancel action when available
    
    ## When not to use
    - The value is guessed or jumps unpredictably
    - Only the content shape, not completion, matters
    
    ## Acceptance criteria
    - Minimum, maximum, and current value are real
    - A visible or accessible label names the operation
    - Updates are understandable rather than noisy
    - Completion, failure, and cancellation have final states
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • Web platform
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The need is tied to canonical behavior before any technical choice.
    • States, accessibility, and non-goals prevent a merely visual implementation.
    • Acceptance criteria and the output format make verification observable.

    Try next

    Verify Progress bar on a real journey

    # Verify Progress bar after implementation
    
    ## Objective
    Audit the Progress bar implementation against its behavior, states, and accessibility requirements without changing it automatically.
    
    ## Checks
    - Replay the smallest representative journey.
    - Check keyboard behavior, focus, accessible name, and announcements.
    - Tie each gap to a specific acceptance criterion.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:9c6137e2f9cd57e453ba01e247450339be6eb8478e35cc7d5ce22ba5c5f474f2

    Diagnose a problem

    Find and fix the Progress bar defect

    # Debug Progress bar in your agent
    
    ## Observed symptom
    [DESCRIBE THE SYMPTOM HERE]
    
    ## Observable checks
    - Reproduce the issue with the smallest relevant journey.
    - Compare behavior with the documented states and transitions for Progress bar.
    - Verify keyboard behavior, focus, accessible name, and announcements.
    
    ## Possible causes
    - The chosen primitive does not match the expected behavior.
    - A state, transition, or focus return is missing.
    - A neighboring component captures an event or hides an accessible signal.
    
    ## Bounded corrections
    - Fix the reproduced cause without recreating neighboring components.
    - Preserve the public contract and add a focused regression test.
    - Do not install dependencies or change remote state without authorization.
    
    ## Final verification
    - Minimum, maximum, and current value are real
    - A visible or accessible label names the operation
    - Updates are understandable rather than noisy
    - Completion, failure, and cancellation have final states
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • Web platform
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The explicit symptom prevents starting from an assumed fix.
    • Checks separate behavior, accessibility, and neighboring interference.
    • The fix stays bounded and must produce regression evidence.

    Try next

    Lock in the Progress bar fix

    # Prevent the Progress bar regression
    
    ## Objective
    Turn the reproduced cause into a focused regression test and compare Progress bar with neighboring concepts before widening the fix.
    
    ## Checks
    - Prove that the test fails before the fix.
    - Prove that it passes after the bounded fix.
    - Verify that no neighboring component changed behavior.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:2feb1cc80fc0079cee31339c0dde05cccd5b7d7c1d8eacb9a8fdc7fc5da2c519

    Full entry, saving and provenance

    Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.

    Pack digest: sha256:757b824e530e221284217c0196ec6b20da468c05c74486322d28c0247e56aa2f

    In code

    TechnologyPrimitiveVersionCaveat
    Web platform

    progress

    NativeUse progress when a current value and maximum are meaningful; omitting the value represents indeterminate progress.

    Technical details

    Behaviors

    • Update measurable progress

      The current value advances within a known minimum and maximum without excessive announcements.

    • Mark the region busy

      The content region exposes its busy state while a separate visual indicator remains redundant.

    States

    • Upload idle

      Upload idle

    • Upload with measured progress

      Upload with measured progress

    • Upload without a reliable estimate

      Upload without a reliable estimate

    • Upload cancelled

      Upload cancelled

    • Upload complete

      Upload complete

    State transitions

    • Upload idle → Upload with measured progress

      Start upload initializes the measured example at 25 percent of 20 MB.

    • Upload with measured progress → Upload complete

      Complete sets the measured value to 100 percent and announces the finished upload.

    • Upload with measured progress → Upload without a reliable estimate

      Simulate unavailable estimate removes the progress value while keeping the upload active.

    • Upload without a reliable estimate → Upload with measured progress

      Restore estimate returns to the preserved measured value.

    • Upload with measured progress → Upload cancelled

      Cancel stops the measured upload and exposes Restart.

    • Upload without a reliable estimate → Upload cancelled

      Cancel stops the upload even when no reliable estimate is available.

    • Upload cancelled → Upload with measured progress

      Restart begins the measured example again at 25 percent.

    • Upload without a reliable estimate → Upload complete

      Complete finishes the upload and reports 100 percent even after the estimate became unavailable.

    • Upload complete → Upload idle

      Reset restores the replayable upload example to zero.

    Test scenarios

    Context
    A 20 MB video upload reports reliable bytes transferred and supports cancellation.
    Mission
    Start the upload, observe a mid-progress value, cancel, restart, and reach the completed state.
    Primary state
    The labeled progress element exposes bytes and percentage while the file transfers.
    Edge case
    If the server stops providing reliable values, the UI switches honestly to an indeterminate busy state instead of faking progress.

    Visual signals

    • Track with a proportional filled value
    • Optional textual percentage or step
    • Stable placement beside the operation

    Behavioral signals

    • Value moves within known minimum and maximum
    • Updates are throttled to remain understandable
    • Completion leads to a clear final state

    Accessibility

    Role
    progress
    Accessible name
    The primary control or named region for Progress bar has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    Focus
    The progress indicator does not receive focus; focus remains on the operation controls or current task.
    Dismissal
    It ends only on completion, failure, or explicit cancellation and is replaced by the matching final status.
    Scroll
    Loading and replacement content reserve enough space to prevent layout jumps and preserve the user's scroll position.
    Announcement
    The accessible name and current value are exposed; announcements are paced to avoid reading every tiny update.
    Keyboard
    • Tab skips the noninteractive bar
    • Tab reaches a separate Cancel action when available

    Bindings

    Open the HTML, ARIA, Radix, and shadcn matrix
    • progress

      implementationKind
      native
      nativeElement
      progress
      ariaPattern
      progressbar
      radixPrimitive
      Not applicable
      shadcnRecipe
      Not applicable
      runtimeDependency
      Not applicable
      packageName
      Not applicable
      exportName
      Not applicable
      exactVersion
      Not applicable
      status
      verified
      sourceId
      source-ui-html-progress
      deprecationStatus
      active
      replacement
      Not applicable
      validFrom
      Not applicable
      validUntil
      Not applicable

      Equivalence caveat: Use progress when a current value and maximum are meaningful; omitting the value represents indeterminate progress.

      Verify binding source

    Sources

    • WHATWG HTML: The progress element
      sourceId
      source-ui-html-progress
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/form-elements.html#the-progress-element
      publisher
      WHATWG
      sourceRevision
      http-last-modified:2026-07-19T13:52:46Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:418a8f9ce1e8690c6d458121120b0b3b7cd907aa92b2101b85f82f7e02d5ac2f
      status
      verified

      Claim covered: Progress bar: normative native semantics, states, attributes, and browser behavior for progress.

    • WCAG 2.2: Status Messages
      sourceId
      source-ui-wcag-understanding-status-messages
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-02T10:07:49Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:cf2a8c16b20c1a94164c9a37e2b3f15d9a7d3f47d88385d47432d6a29655609e
      status
      verified

      Claim covered: Progress bar: informative WCAG guidance for status messages announced without moving focus.

    • WAI-ARIA 1.2: Roles Model
      sourceId
      source-ui-wai-aria-roles
      kind
      standard
      canonicalUrl
      https://www.w3.org/TR/wai-aria-1.2/#roles
      publisher
      W3C WAI
      sourceRevision
      W3C-REC-wai-aria-1.2-20230606
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:c0fea16fc747779569ab754d2d25bca3e2b7e8a673b8ef5362aeb9ebc73a4849
      status
      verified

      Claim covered: Progress bar: normative ARIA role definitions and constraints for the stated accessible role.

    • WAI-ARIA 1.2: aria-busy
      sourceId
      source-ui-wai-aria-busy
      kind
      standard
      canonicalUrl
      https://www.w3.org/TR/wai-aria-1.2/#aria-busy
      publisher
      W3C WAI
      sourceRevision
      W3C-REC-wai-aria-1.2-20230606
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:c0fea16fc747779569ab754d2d25bca3e2b7e8a673b8ef5362aeb9ebc73a4849
      status
      verified

      Claim covered: Progress bar: the normative aria-busy state for exposing a region while its content is updating.

    • WAI-ARIA 1.2: Live Region Attributes
      sourceId
      source-ui-wai-aria-live-regions
      kind
      standard
      canonicalUrl
      https://www.w3.org/TR/wai-aria-1.2/#attrs_liveregions
      publisher
      W3C WAI
      sourceRevision
      W3C-REC-wai-aria-1.2-20230606
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:c0fea16fc747779569ab754d2d25bca3e2b7e8a673b8ef5362aeb9ebc73a4849
      status
      verified

      Claim covered: Progress bar: normative live-region properties for status announcement behavior.