Get startedFoundationsComponentsTemplatesBlocksAIStories
Browse Components

Components

AccordionAlertBadgeBreadcrumbButtonCard groupCardIcon cardImage cardThumbnail cardCheckboxClose buttonCombo boxDatepickerDescription listDividerDrawerDropdownFile uploadFooterIcon buttonIcon listInputLinkMainnavMastheadModalOverflow menuPaginationProgress barQuantity toggleRadioSelectSidebarSidenavSkeletonSpinnerStepperSubnavSwitchSystem bannerTabTableTable of contentsTextareaToastTooltip

Progress bar

Provide up-to-date feedback on the progress of a workflow or action with a progress bar.

GitHub
Storybook
DesignUsageAccessibilityUpdates

Purpose

Show ongoing progress

Use a progress bar when a task has measurable completion.

Show how much is done

The filled track helps users see progress against the full amount.

Support longer waits

Progress feedback reassures users during uploads, setup, or processing.

Anatomy

1

Active indicator

2

Track

3

Label (optional)

Configuration

Variant

Progress bars come in two visual tones. Pick the one that matches the surrounding surface.

Brand-coloured fill. Use for the dominant progress indicator on a page.

Value

The current progress as a percentage from 0 to 100.

Type a value to set progress to 30%.

Label

Optional text label rendered above the bar to describe what is loading.

Adds a descriptive label above the bar to clarify the running task.

Structure

Design tokens used

Each row is a colour, spacing, or size value the component uses, and the right-most column tells you where in the component you'll see it.

CategoryTokenValueWhere it's usedGapsgds-gap-2-xs4pxSpacing between items of the progress containerTypographysgds-font-size-14—Font size of the labelSizesgds-dimension-4—Height of the progress bar

Usage

When to use

  • Use this component to communicate a clear system state, status, or next step at the right moment.
  • Use it when users need immediate feedback that is tied to a task, outcome, or page context.

When not to use

  • Do not use this component for routine body content that should stay in the normal page flow.
  • Do not stack multiple messages of the same priority when one clear message is enough.

Best practices

Use a progress bar when progress is measurable

Use a progress bar only for operations with a known endpoint. Use a spinner for indeterminate waits.

Do not use a progress bar for unknown durations

If progress cannot be calculated, do not fake it. A bar that creeps forward misleads users. Use a spinner.

Label the running task

Add a label that names what is happening. A bar without context tells users that something is loading but not what.

Do not use progress as failure feedback

Progress bars are for in-flight progress, not errors. If an operation fails, stop the progress state and show an alert.

Always provide an accessible label

Set arialabel so screen reader users know what is progressing. Pair it with a visible label when the surrounding context is not enough.

Do not let progress fall outside its range

Keep value within ariamin and ariamax. Out-of-range values can render as empty or overflow and misrepresent the task.

Use the neutral variant for secondary progress

When a page already shows a primary progress bar, use the neutral variant for any secondary progress.

Do not rely on the bar alone for completion

When value reaches ariamax, show a success message, next action, or completion state. The component does not trigger completion feedback by itself.

Accessibility considerations

Built-in accessibility

  • Progress bars expose progress semantics with role="progressbar".
  • The component supports accessible value attributes and an accessible label.

Labels and content

  • Use a clear label when the progress bar needs context.
  • Keep the value, minimum, and maximum accurate as progress changes.

Focus and interaction

  • Progress bars should not receive focus unless paired with an interactive control.
  • Use status text nearby when users need to know what is happening.

Keyboard interaction

This component does not have a separate keyboard interaction table because:

  • Progress bars communicate status and usually should not receive focus.
  • Keyboard interaction belongs to any related control, such as a cancel or retry button.

Updates

DateVersionDescription

Roadmap

Planned itemStatusTargetFuture enhancements for progress barPlannedTBD

Feedback

Have suggestions or feedback?

Share them with us on Slack → #ask-sgds-v3

Bug Reports

Found a bug or issue?

Report it on GitHub Issues → sgds/components/progress-bar

Singapore Government Design System

The Singapore Government Design System was developed to empower teams in creating fast, accessible and mobile-friendly digital services.

Past VersionsSGDS v1SGDS v2