Quickstart: adding progress controls (HTML)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Progress controls provide a way for you to indicate that your app is performing work, such as downloading images, loading files, or processing data. Here are the different progress control styles and how to add them to a Windows Runtime app using JavaScript.

Prerequisites

We assume that you can create a basic Windows Runtime app using JavaScript. For help creating your first app, see Building your first Windows Windows Runtime app using JavaScript. For help creating your first controls and adding event handlers, see Quickstart: adding controls and event handlers.

Progress control styles

There are three styles of progress controls that indicate to the user when the amount of work to complete is known, when it isn’t, and whether the task is modal: the determinate progress bar style, the indeterminate progress bar style, and the indeterminate ring style.

Determinate Progress Bar: Shows how much progress the app has made. As work progresses, a fill color expands from left to right until it fills the progress bar.
Indeterminate Progress Bar: Indicates that users can interact with the UI while the task continues. In the animation, dots appear on the left and move to the right along a track until they reach the end of the track and disappear.
Indeterminate Progress Ring (Windows only): Indicates that user activity is blocked until the app completes the task, that is, the activity is modal. In the animation, several dots move clockwise in a circle.

 

Adding a determinate progress bar

A determinate progress bar shows how much progress the app has made. As work progresses , the bar fills up. If you can estimate remaining amount of work in time, bytes, files, or some other quantifiable units of measure, use a determinate progress bar. For more info about when to use a determinate progress bar, see the Guidelines and checklist for progress controls.

The progress bar provides 3 properties for setting and determining progress:

Property	Description
max	A number that specifies the value of completion. The default value is 1.0.
value	A number that specifies the current progress. If you're showing the progress of a file download, this value might be the number of bytes downloaded (and then you set max to the total number of bytes to download).
position	(Read-only.) The current progress indicator, which is value divided by max.

 

To create a determinate progress bar

To create a determinate progress bar, you create a progress element and set its value property. If you don't want to use the default completion value of 1.0, you can change it by setting the max property. This example creates a determinate progress bar and sets its value to 30 and its max to 100. The resulting progress bar shows that progress is 30% complete.

<progress id="determinateProgressBar" value="30" max="100"></progress>

To update the value of a determinate progress bar

The previous example showed how to specify the value of a progress bar in markup. In a real app, you use JavaScript to update the value of the progress bar as a response to some indicator of progress. For example, if your progress bar indicates how many files have been downloaded, you update the value each time another file is downloaded.

This example updates the value of a the progress bar.

var progressBar = document.getElementById("determinateProgressBar");
progressBar.value = value;

Adding an indeterminate progress bar

When you can't estimate how much work remains to finish a task and the task doesn't block user interaction, use an indeterminate progress bar. Instead of showing a bar that fills up as progress completes, an indeterminate progress bar shows an animation of dots moving from left to right. For more info about when to use an indeterminate progress bar, see Guidelines and checklist for progress controls.

To create an indeterminate progress bar

To create an indeterminate progress bar, create a progress element without specifying a value or max.

<!-- Create an indeterminate progress bar -->
<progress></progress>

Adding an indeterminate progress ring (Windows only)

When you can't estimate how much work remains to finish a task and the task does block user interaction, use an indeterminate progress ring. An indeterminate progress ring shows an animate sequence of dots moving in a circle. For more info about when to use an indeterminate progress ring, see Guidelines and checklist for progress controls.

To create an indeterminate progress ring

To create an indeterminate progress ring, create a progress element without specifying a value or max and set its class to win-ring.

<progress class="win-ring"></progress>

(The win-ring class is one of the styles provided by the Windows Library for JavaScript.)

The next example shows how to create an indeterminate progress ring that also displays text.

<label class="progressRingText">
    <progress class="win-ring withText"></progress>Processing</label>

Here are the CSS styles that accompany the preceding example.

progress.withText
{
    color: inherit; /* Uses the same text color as the page */
    vertical-align: text-bottom; /* Makes the bottom of the control align with the bottom of its label */
}

/* Text style for a label for the progress ring */
.progressRingText
{
    font-family: "Segoe UI";
}

/* Text style for a label for a default size progress ring */
.progressRingText
{
    font-size: 11pt;
    line-height: 15pt;
}

/* The margin to separate the ring and its label */
.progressRingText progress
{
    margin-right: 5px;
}

Summary and Next Steps

You learned how to create different types of progress controls.

In the next topic, How to style progress controls, you learn more about using CSS and WinJS classes to style your progress controls.

After that, check out the Guidelines and checklist for progress controls, which goes into more detail about when and how to use the progress control.

Related topics

progress

How to style progress controls

Guidelines and checklist for progress controls