progress

A control that can show the progression of some operation.

Properties¶

Name	Type	Default	Description
`value`^(★)	`int` dynamic	None	The progress percentage represented by the control. If this property is not set or set to None, the progress control represents an indeterminate state.
`linear`	`bool`	False	If set to True, the control displays a linear progress indicator instead of a circular one.
`show_value`	`bool`	False	If set to True, the progress value is shown.
`title`	`str` dynamic		The title of the progress indicator.
`title_anchor`	`str`	"bottom"	The anchor of the title. Possible values are: "bottom" "top" "left" "right" "none" (no title is displayed)
`render`	`bool` dynamic	True	If False, this progress indicator is hidden from the page.
`width`	`Union[str,int]`	None	The width of this progress indicator, in CSS units.

^(★)value is the default property for this visual element.

Details¶

The progress indicator represents, in a compact way, the ratio of achievement on a scale from 0 to 100 percent.
It is useful in situations where a lengthy process is underway, and the application needs to reflect how much of the task has been completed at any given moment.

The progress is represented as a ring, or an horizontal bar if the linear property is set to True.
The amount of the shape that is filled correlates with the percentage. The unfilled portion of the circle or the bar represents the remaining progress.

The percentage value can be displayed by setting the show_value property is set to True.
The control can also display a title (using the title) that can be displayed at different locations, depending on the setting of the title_anchor property.

Note that is the value property is set to None, the progress control shows an indeterminate state.

Usage¶

Circular progress indicator¶

See the entire code for this example

The simplest and most compact use case for the progress control is a circular progress indicator.
How much of the indicator's ring is filled reflects the percentage of achieved progress.

We store the percentage to represent in a Python variable:

value = 72

The control definition is as simple as it gets:

Definition

MarkdownHTMLPython

<|progress|value={value}|>

<taipy:progress value="{value}"/>

import taipy.gui.builder as tgb
...
tgb.progress(value="{value}")

And the result looks like this:

Linear progress indicator¶

See the entire code for this example

You can change the representation of the control to a horizontal bar by setting the linear property to True.

Using the same variable as above, this would be the control definition:

Definition

MarkdownHTMLPython

<|progress|value={value}|linear|>

<taipy:progress value="{value}" linear/>

import taipy.gui.builder as tgb
...
tgb.progress(value="{value}", linear=True)

This is how the control now looks:

Adding a title¶

See the entire code for this example

The control can show the percentage as a numerical value by setting the show_value property to True.
You can add a title to the control with the title property. You can also specify the location of the title, relative to the whole control, with the title property.

With the same variable as above, this is the control definition of a progress indicator showing a title above the gauge:

Definition

MarkdownHTMLPython

<|progress|value={value}|title=Processing...|title_anchor=top|show_value|>

<taipy:progress value="{value}" title="Processing..." title_anchor="top" show_value/>

import taipy.gui.builder as tgb
...
tgb.progress(value="{value}", title="Processing...", title_anchor="top", show_value=True)

The value is displayed explicitly, and the title is shown as expected:

Styling¶

All the progress controls are generated with the "taipy-progress" CSS class. You can use this class name to select the date selectors on your page and apply style.

Circular and linear progress indicators have slightly different implementations, impacting how styling must be defined.

Circular indicator¶

See the entire code for this example

The implementation of the progress control is based on the MUI CircularProgress component.
The CSS classes that can be used are documented here.

Here is how you can change the ring color and width. The CSS rules that are used are the following:

.taipy-progress .MuiCircularProgress-circle {
    stroke: green;
    stroke-width: 2;
}

The class MuiCircularProgress-circle is set on the SVG element that holds the ring.

Here is the impact of this rule:

Linear indicator¶

See the entire code for this example

The linear version of the progress control relies on the MUI LinearProgress component.
The CSS classes that can be used are documented here.

Here is how you can change the colors of the bar and its height.
Here are the CSS rules:

.taipy-progress {
    background-color: red;
    .MuiLinearProgress-root {
        height: 30px;
        .MuiLinearProgress-barColorPrimary {
            background-color: green;
         }
    }
}

The background-color of the taipy-progress part applies to the entire bar.
The class MuiLinearProgress-root is set on the element holding the complete linear bar and MuiLinearProgress-barColorPrimary applies to the filled area.

Here is the result of applying this style:

Styling texts¶

See the entire code for this example

The progress control provides the CSS class taipy-progress-value to the element that displays the value.
Similarly, the CSS class taipy-progress-title applies to the element displaying the title.

The following rules make the value appear in blue and enlarge the size of the font used for the title:

.taipy-progress-value {
    color: blue;
    font-weight: bold;
}
.taipy-progress-title {
    font-size: 1.5em;
}

Resulting to this: