Feedback · Progress
Progress
Used to display the current progress and status of the user operation, and is generally used when the operation takes a long time. Can also be used to indicate the degree of completion of a task/object

Demos

How to import

Standard progress bar

Use stroke Property to control the filling color of the progress bar
Use Percent Property to control completed progress
Use size Property control progress bar size
Use aria-label Property to explain the specific role
If the preset size is not satisfied, You can pass height to customize the height of the progress bar through style property.

Show percentage text

You can control whether to show percentage number through the showInfo property In addition, you can format the percentage text show through format.

Vertical progress bar

You can use vertical progress bar by setting direction='vertical' If preset width is not satisfied, you can pass width to customize the width of the vertical progress bar through style property.

Circular progress bar

Set type tocircle, the progress bar will be displayed in a ring shape. The default size of the progress bar is 72 x 72
You can modify it's width to control the size of the circular progress bar.

Small circular progress bar

Small progress bar default size is 24 x 24.

Dynamic change percent

Custom central text content

You can customize the central text by passing format function, and the argument of the format is the current percentage
If you don't need central text content, you can set showInfo to false or return an empty string directly in format

Round / square edges

With the strokeLinecap property, you can control the edge shape of the ring progress bar.

Customise the progress bar color

The color of a specific percent can be customised by setting the stroke property

Auto-completion of colour intervals

The gradient can be generated by setting the strokeGradient property to true, automatically fill the colour interval.

API Reference

PROPERTIESInstructionsTypeDefault
aria-labelaria-label attribute. Used to add a label description to the current element to improve a11y
provided after v2.2.0
string
aria-labelledbyaria-labelledby attribute. Indicates that the id of some element is the label of the current element. It is used to determine the connection between controls or control groups and their labels, to improve a11y
provided after v2.2.0
string
aria-valuetextaria-labelledby attribute. Used to improve a11y
provided after v2.2.0
string
classNamestyle class namestring
directionThe direction of the bar progress bar horizontal, verticalstring'horizontal'
idid attribute
provided after v2.2.0
string
formatFormatting function, the input parameter is the current percentage, the result of return will be directly rendered in the center of the circular progress bar(percent: number) => ReactNode(percent) => percent +'%'
orbitStrokeProgress bar track fill color
provided after v1.0.0
string'var(--semi-color-fill-0)'
percentpercentage of progressnumber
showInfoWhether to display the middle text in the circular progress bar, and whether to display the text on the right side of the bar-shaped progress barbooleanfalse
sizesize, optional default, small (only type=circle is effective), large (only type=line is effective)string'default'
strokeFill color of progress bar, When of type Array<{percent:number; color:string }>, the color parameter supports the color types: 'Hex' | 'Hsl' | 'Hsla' | 'Rgb' | 'Rgba' | 'Semi Design Tokens'string | Array<{percent:number; color:string }>'var(--semi-color-success)'
strokeGradientWhether to automatically generate gradient colors to fill color intervals, requires stroke to set at least one color intervalbooleanfalse
strokeLinecapround corner round/square corner square (only effective in type='circle' mode)string'round'
strokeWidthwhen type is circle, this property controls the width of the progress barnumber4
stylestyleCSSProperties
typetype, optional line, circlestring'line'
widthWidth of circular progress barnumber72 when size='default', 24 for 'small'

Accessibility

ARIA

  • Progress has a progressbar role to indicate that it is a progress bar component.
  • Progress will automatically set aria-valuenow as the progress percentage (percent) passed to the component to ensure that the screen reader can get the correct percentage value. In addition, Progress supports incoming aria-valuetext. When you pass in, according to W3C specifications, aria-valuetext will be used and consumed by screen readers instead of aria-valuenow
  • Progress support aria-label, aria-labelledby
    • When there is a description element about the role of Progress outside of Progress, you can explicitly specify that the id of certain elements is the label of Progress through aria-labelledby
    • Otherwise, you should use aria-label to explain the specific meaning of the value represented by Progress

Content Guidelines

  • If the progress bar process is complicated, or there is a long waiting time, you can use the help text to explain. This lets the user know what progress is happening.

Design Tokens