Components/ProgressBar

ProgressBar

A bar that shows determinate, indeterminate, or segmented progress.

VerifiedSince 0.3.4

Usage

The base bar, with indeterminate, loading, segmented, upload-detail, and tooltip modes; for a row-level percentage, use Progress.

States

status sets the status color; success marks completion and loading marks work of unknown duration.

Loading demo...

Upload Progress

textPlacement="top" and "bottom" put a text row with detail above or below the track; flowEffect="stardust" drifts star points over a flat or gradient fill.

Loading demo...

Segments

Hovering a segment shows its label and its share of segmentsTotal; leave room above the bar for the tip.

Loading demo...

Operations Panel

Combined with metric cards and status badges to show dashboard health.

Loading demo...

Status Panel

Loading demo...

Best Practices

  • Use percentage only when progress is known; use loading or indeterminate when the duration is unknown.
  • On completion, pass success with a short message instead of faking 100%.
  • Keep message short because it doubles as the accessible name; put upload and download amounts in detail with textPlacement="top" or "bottom".
  • To keep the text inside the track, set height to at least 16px and keep the label short; on a thinner track, or one narrower than the label, inside text shows below it.
  • Give every segment a label, and set segmentsTotal when segments cover only part of a total.
  • Reserve flow effects for high-value progress; too much shimmer, wave, or stardust makes a dashboard noisy.

API Reference

Props

PropTypeDefaultDescription
loadingbooleanfalseIndeterminate loading mode.
indeterminatebooleanfalseIndeterminate mode that doesn't imply loading.
indeterminateVariant'classic' | 'sweep' | 'bounce' | 'elastic' | 'split''sweep'Animation for loading / indeterminate states.
errorbooleanfalseError state; overrides status.
successbooleanfalseSuccess state; overrides status.
status'success' | 'error' | 'warning' | ''''Status color.
messagestring''Visible text that also serves as the accessible name.
detailstring''Secondary copy, shown only in a text row above or below the track (top, bottom, or inside on a track the text doesn't fit); never part of the accessible name.
ariaLabelstring''Accessible name; falls back to message, then 'Progress'.
percentagenumber0Determinate value, clamped to 0..100.
segmentsProgressSegment[]-Multi-segment progress data.
segmentsTotalnumber100Total used for the filled width when segments is set.
heightstring'5px'Bar height.
showTextbooleanfalseShows percentage text for determinate progress.
textPlacement'inside' | 'outside' | 'top' | 'bottom''inside'Text position; top and bottom put a text row with detail above or below the track; inside renders as bottom on a track under 16px or narrower than the label.
format(percentage: number) => string-Custom percentage text.
flowEffect'none' | 'shimmer' | 'wave' | 'stardust' | 'particles''none'Fill effect; particles is a deprecated alias of stardust. Ignored for segments.
indicatorEffect'none' | 'sparkle''none'Endpoint effect once progress is above zero.
hoverEffect'none' | 'glow''none'Wrapper hover effect.
colorstring-Custom fill color over the status color; gradient strings are used as-is.
maskVariant'solid' | 'dashed' | 'plain''plain'Track rim; plain draws none.
maskBackground'none' | 'blur' | 'glass' | 'mask''none'Track mask layer; none renders no mask node.
tooltipbooleanfalseShows a tooltip with the resolved text.
tooltipContentstring-Overrides the tooltip content.
tooltipPropsPartial<TooltipProps>-Props forwarded to TxTooltip.

Events

EventPayloadDescription
complete-Fires once per completion cycle when progress reaches 100; fires again after it drops and completes again.

Types

ProgressSegment:

FieldTypeDescription
valuenumberSegment value; only positive finite values render.
colorstringSegment fill; falls back to the bar's fill color.
labelstringPrecedes the share in the hover tip (Video · 25%); without it the tip shows the share alone.

Overview

  • The track is role="progressbar" (aria-valuemin="0", aria-valuemax="100"); aria-valuenow is the clamped value and is omitted while loading or indeterminate.
  • Text resolves from message, then format, then the rounded percentage. It shows only with message or showText, and only message shows while loading or indeterminate.
  • inside keeps the text in the track only while the track is at least one 16px line tall and as wide as the label, and colours it ink over the unfilled part and white over the fill; otherwise, including on the default 5px track, it renders as bottom. Elsewhere a long label wraps to at most two lines: detail keeps one line within 60% of the row, and outside text takes at most half of it.
  • Inside a TxTooltip — its own tooltip, or a host's that wraps the bar directly — the bar keeps its full width instead of shrinking to its text.
  • When success or error has a message and percentage is 0, the fill width resolves to 100%.
  • Segments skip non-positive values: the overall fill uses segmentsTotal, and widths inside it normalize by the positive sum.
  • Width changes ease over 480ms; indeterminate animations touch only transform and opacity, and stop under reduced motion.

Technologies

  • The fill defaults to a faded-to-saturated linear-gradient, and the tip glow shows only strictly between 0% and 100%; a gradient color gets a white glow. The inside label's two copies are clipped at --tx-progress-width and ease on the fill's 480ms curve, so the colour split stays on the fill's edge.
  • The hoverEffect="glow" shadow and indicatorEffect="sparkle" sparks sit inside the overflow: hidden track and are clipped to its height.
  • Whether the text fits in the track is read from height during SSR and on the first frame: px compares directly, rem and em convert at 16px per unit, and %, calc() and var() count as fitting. Once mounted, a ResizeObserver on the track and the label compares the track's real height with the label's line height and its width with the label's; the label stays mounted, hidden, while the text is below, so it can be measured again, and the observer disconnects on unmount.
  • Source: packages/tuffex/packages/components/src/progress-bar/.
查看源码
packages/tuffex/packages/components/src/progress-bar/index.ts