ProgressBar
A bar that shows determinate, indeterminate, or segmented progress.
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
percentageonly when progress is known; useloadingorindeterminatewhen the duration is unknown. - On completion, pass
successwith a shortmessageinstead of faking 100%. - Keep
messageshort because it doubles as the accessible name; put upload and download amounts indetailwithtextPlacement="top"or"bottom". - To keep the text inside the track, set
heightto at least16pxand keep the label short; on a thinner track, or one narrower than the label,insidetext shows below it. - Give every segment a
label, and setsegmentsTotalwhen 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
| Prop | Type | Default | Description |
|---|---|---|---|
loading | boolean | false | Indeterminate loading mode. |
indeterminate | boolean | false | Indeterminate mode that doesn't imply loading. |
indeterminateVariant | 'classic' | 'sweep' | 'bounce' | 'elastic' | 'split' | 'sweep' | Animation for loading / indeterminate states. |
error | boolean | false | Error state; overrides status. |
success | boolean | false | Success state; overrides status. |
status | 'success' | 'error' | 'warning' | '' | '' | Status color. |
message | string | '' | Visible text that also serves as the accessible name. |
detail | string | '' | 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. |
ariaLabel | string | '' | Accessible name; falls back to message, then 'Progress'. |
percentage | number | 0 | Determinate value, clamped to 0..100. |
segments | ProgressSegment[] | - | Multi-segment progress data. |
segmentsTotal | number | 100 | Total used for the filled width when segments is set. |
height | string | '5px' | Bar height. |
showText | boolean | false | Shows 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. |
color | string | - | 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. |
tooltip | boolean | false | Shows a tooltip with the resolved text. |
tooltipContent | string | - | Overrides the tooltip content. |
tooltipProps | Partial<TooltipProps> | - | Props forwarded to TxTooltip. |
Events
| Event | Payload | Description |
|---|---|---|
complete | - | Fires once per completion cycle when progress reaches 100; fires again after it drops and completes again. |
Types
ProgressSegment:
| Field | Type | Description |
|---|---|---|
value | number | Segment value; only positive finite values render. |
color | string | Segment fill; falls back to the bar's fill color. |
label | string | Precedes 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-valuenowis the clamped value and is omitted whileloadingorindeterminate. - Text resolves from
message, thenformat, then the rounded percentage. It shows only withmessageorshowText, and onlymessageshows whileloadingorindeterminate. insidekeeps the text in the track only while the track is at least one16pxline tall and as wide as the label, and colours it ink over the unfilled part and white over the fill; otherwise, including on the default5pxtrack, it renders asbottom. Elsewhere a long label wraps to at most two lines:detailkeeps one line within 60% of the row, andoutsidetext takes at most half of it.- Inside a
TxTooltip— its owntooltip, or a host's that wraps the bar directly — the bar keeps its full width instead of shrinking to its text. - When
successorerrorhas amessageandpercentageis0, the fill width resolves to100%. - 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
transformandopacity, 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 gradientcolorgets a white glow. The inside label's two copies are clipped at--tx-progress-widthand ease on the fill's480mscurve, so the colour split stays on the fill's edge. - The
hoverEffect="glow"shadow andindicatorEffect="sparkle"sparks sit inside theoverflow: hiddentrack and are clipped to its height. - Whether the text fits in the track is read from
heightduring SSR and on the first frame:pxcompares directly,remandemconvert at16pxper unit, and%,calc()andvar()count as fitting. Once mounted, aResizeObserveron 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