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.
User agent requirements: If the value
attribute is omitted, then
the progress bar is an indeterminate progress bar. Otherwise, it is
a determinate progress bar.
If the progress bar is a determinate progress bar and the element
has a max
attribute, the user
agent must parse the max
attribute's value according to the rules for parsing
floating-point number values. If this does not result in an
error, and if the parsed value is greater than zero, then the maximum value of the progress
bar is that value. Otherwise, if the element has no max
attribute, or if it has one but
parsing it resulted in an error, or if the parsed value was less
than or equal to zero, then the maximum value of the
progress bar is 1.0.
If the progress bar is a determinate progress bar, user agents
must parse the value
attribute's value according to the rules for parsing
floating-point number values. If this does not result in an
error, and if the parsed value is less than the maximum value and greater
than zero, then the current
value of the progress bar is that parsed value. Otherwise, if
the parsed value was greater than or equal to the maximum value, then the
current value of the
progress bar is the maximum
value of the progress bar. Otherwise, if parsing the value
attribute's value resulted
in an error, or a number less than or equal to zero, then the current value of the progress
bar is zero.
UA requirements for showing the progress bar:
When representing a progress
element to the user, the
UA should indicate whether it is a determinate or indeterminate
progress bar, and in the former case, should indicate the relative
position of the current
value relative to the maximum value.
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
position
IDL
attribute must return −1. Otherwise, it must return the
result of dividing the current value by the maximum value.
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.
Setting the value
IDL attribute to itself when
the corresponding content attribute is absent would change the
progress bar from an indeterminate progress bar to a determinate
progress bar with no progress.
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.
The labels
IDL attribute
provides a list of the element's label
s.