# Progress bar
Display progress using progress bars and horizontally stacked multiple bars
There are two components that can be used to create progress bars: <bdn-progress> and <bdn-progress-bar>.
If you need simple progress bar with variants, simple labels, custom colors etc, you can use the <bdn-progress>
component.
If you, however, need horizontally stacked bars, or you need more complex labels inside your bars, which cannot be done
through label prop, you need to use <bdn-progress> component in combination with <bdn-progress-bar>. In this case,
the max and height (if necessary) props should be placed on <bdn-progress> component, and value, variant, and
all others should be placed on each <bdn-progress-bar> component.
Examples are provided below.
WARNING
Please note that in <bdn-progress> default slot you can only put <bdn-progress-bar> component,
and <bdn-progress-bar> cannot be used as a standalone component, it has to be a child of <bdn-progress>.
# Examples
# Setting values
In order for progress bar to work, you need to define maximum and current value, through props max and value.
Default value for max prop is 100.
# Adding labels
Labels for bars can be added using the prop label, or using the default slot in <bdn-progress-bar> component.
If you want to display a percentage of progress value in regard to maximum value, you can simply use the show-progress
prop. Note that label prop has precedence over show-progress, so if you provide both, what's in label prop will be
shown.
By default, show-progress will round the percentage to closest integer, but you can control this through precision prop,
which takes values from 0 to 5. So, if you would put precision="2" the label would have 2 decimals.
Also, labels can be positioned to start, center or end of the bar using the prop align-label. The default position is
center, and possible values are start, center, and end.
Check out the examples below.
Simple label
Automatic percentage label
Automatic percentage label with two decimals
Label in slot
Label aligned left
Label aligned center
Label aligned right
# Color variants
There are 7 predefined color variants: primary, secondary, info, success, warning, danger and transparent.
Transparent variant can be used in some special cases, as labels cannot be placed just anywhere, take a look at an example below.
Primary
Secondary
Info
Success
Warning
Danger
Transparent variant use case (see code)
# Custom colors
In addition to predefined color variants, you can define your own colors for progress bars, using
props custom-bar-color and custom-text-color. Note that the background of the track cannot be changed with props,
yet.
# Custom height
The default progress bar height is 15px, but you can define height as necessary using the height prop.
If you want progress bar to adjust to the label or the content in slot, set height="auto".
Default height
Height 5px
Height 24px
Height 40px
Height auto
# Animated bars
If you need to show some sort of loading with progress bar, you can add additional animation to it. Simply provide the
animated prop to <bdn-progress> or <bdn-progress-bar>, depending on what you are using.
Animated prop on progress component
Animated prop on progress-bar component
Dynamic animation
# Steps
As an additional visual aid for the progress bars, you can include number of steps in your progress bars.
5 steps
12 steps
25 steps
# Multiple (stacked) bars
If you need to show grouped progress bars, simply add multiple <bdn-progress-bar> components inside the <bdn-progress>.
Don't forget to set different colors to bars inside, and make sure the sum of values doesn't exceed the max property.
Stacked progress bars
Dynamic max value
Max value is: 100
# Customization
You can use following SCSS variables to customize the colors of progress bars. Variant colors depend on the variables with the same name.
$progress-border-radius: 500px !default;
$progress-background-color: $plain !default;
$progress-step-color: rgba($text, 0.35) !default;
# Props reference
Except max, height and steps, which can be used only on <bdn-progress>, all other props work on the <bdn-progress-bar>.
| Property | Type | Default | Accepts | Description |
|---|---|---|---|---|
max | Number | 100 | Any positive number | Progress bar maximum, used to calculate percentage of the progress from value prop (only for <bdn-progress></bdn-progress> component) |
value | Number | 0 | Any positive number | A current value of the progress bar |
height | Number | 15 | Any positive number | Height of the progress bar in px (only for <bdn-progress></bdn-progress> component) |
variant | String | primary | primary, secondary, info, success, warning, danger, transparent | The color variant of the progress bar |
label | String | empty | Any string | A label of the progress bar |
show-progress | Boolean | false | true or false | An automatically calculated value in %, in regard to the max value of the progress bar |
precision | Number | 0 | A number between 0 and 4 | Determines the number of decimals when show-progress is active |
align-label | String | center | start, center or end | Determines the alignment of the label inside the progress bar |
custom-bar-color | String | empty | Any valid color code | Determines the fill color of the progress bar |
custom-text-color | String | empty | Any valid color code | Determines the text color of the progress bar |
animated | Boolean | false | true or false | Determines if the progress bar has a 'loading' animation |
steps | Number | 0 | Any number | Displays the 'ticks' on the progress bar, base on the number of steps entered in prop (only for <bdn-progress></bdn-progress> component) |
← Expand Radio button →