progress
elementprogress
element descendants.value
max
interface HTMLProgressElement : HTMLElement { attribute double value; attribute double max; readonly attribute double position; 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 a 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, limited to numbers greater than zero. The
default value for max
is
1.0.