progress
elementprogress
element descendants.value
max
form
interface HTMLProgressElement : HTMLElement { attribute double value; attribute double max; readonly attribute double position; readonly attribute HTMLFormElement form; readonly attribute NodeList labels; };
The progress
element represents the completion progress of a task. The progress is either indeterminate, indicating that progress is being made but that it is not clear how much more work remains to be done before the task is complete (e.g. because the task is waiting for a remote host to respond), or the progress is a number in the range zero to a maximum, giving the fraction of work that has so far been completed.
There are two attributes that determine the current task completion represented by the element. The value
attribute specifies how much of the task has been completed, and the max
attribute specifies how much work the task requires in total. The units are arbitrary and not specified.
To make an determinate progress bar, add a value
attribute with the current progress (either a number from 0.0 to 1.0, or, if the max
attribute is specified, a number from 0 to the value of the max
attribute. To make an indeterminate progress bar, remove the value
attribute.
Authors are encouraged to also include the current value and the maximum value inline as text inside the element, so that the progress is made available to users of legacy user agents.
Here is a snippet of a Web application that shows the progress of some automated task:
<section> <h2>Task Progress</h2> <p>Progress: <progress id="p" max=100><span>0</span>%</progress></p> <script> var progressBar = document.getElementById('p'); function updateProgress(newValue) { progressBar.value = newValue; progressBar.getElementsByTagName('span')[0].textContent = newValue; } </script> </section>
(The updateProgress()
method in this example would be called by some other code on the page to update the actual progress bar as the task progressed.)
The value
and max
attributes, when present, must have values that are valid floating point numbers. The value
attribute, if present, must have a value equal to or greater than zero, and less than or equal to the value of the max
attribute, if present, or 1.0, otherwise. The max
attribute, if present, must have a value greater than zero.
The progress
element is the wrong element to use for something that is just a gauge, as opposed to task progress. For instance, indicating disk space usage using progress
would be inappropriate. Instead, the meter
element is available for such use cases.
position
For a determinate progress bar (one with known current and maximum values), returns the result of dividing the current value by the maximum value.
For an indeterminate progress bar, returns −1.
If the progress bar is an indeterminate progress bar, then the value
IDL attribute, on getting, must return 0. Otherwise, it must return the current value. On setting, the given value must be converted to the best representation of the number as a floating point number and then the value
content attribute must be set to
that string.
The max
IDL attribute must reflect the content attribute of the same name. The default value for max
is 1.0.