meter
elementmeter
element descendants.value
min
max
low
high
optimum
interface HTMLMeterElement : HTMLElement { attribute double value; attribute double min; attribute double max; attribute double low; attribute double high; attribute double optimum; readonly attribute NodeList labels; };
The meter
element represents
a scalar measurement within a known range, or a fractional value;
for example disk usage, the relevance of a query result, or the
fraction of a voting population to have selected a particular
candidate.
This is also known as a gauge.
The meter
element should not be used to
indicate progress (as in a progress bar). For that role, HTML
provides a separate progress
element.
The meter
element also does not represent a
scalar value of arbitrary range — for example, it would be wrong to
use this to report a weight, or height, unless there is a known
maximum value.
There are six attributes that determine the semantics of the gauge represented by the element.
The min
attribute specifies the
lower bound of the range, and the max
attribute specifies the
upper bound. The value
attribute specifies the
value to have the gauge indicate as the "measured" value.
The other three attributes can be used to segment the gauge's
range into "low", "medium", and "high" parts, and to indicate which
part of the gauge is the "optimum" part. The low
attribute specifies the range that is considered to be the "low"
part, and the high
attribute specifies the
range that is considered to be the "high" part. The optimum
attribute gives the
position that is "optimum"; if that is higher than the "high" value
then this indicates that the higher the value, the better; if it's
lower than the "low" mark then it indicates that lower values are
better, and naturally if it is in between then it indicates that
neither high nor low values are good.
The value
attribute must be specified. The
value
, min
, low
, high
, max
, and optimum
attributes, when present, must
have values that are valid floating-point numbers.
In addition, the attributes' values are further constrained:
Let value be the value
attribute's number.
If the min
attribute attribute is specified, then let
minimum be that attribute's value; otherwise,
let it be zero.
If the max
attribute attribute is specified, then let
maximum be that attribute's value; otherwise,
let it be 1.0.
The following inequalities must hold, as applicable:
low
≤ maximum (if
low
is specified)high
≤ maximum (if
high
is specified)optimum
≤ maximum (if
optimum
is specified)low
≤ high
(if both low
and high
are specified)If no minimum or maximum is specified, then the range is assumed to be 0..1, and the value thus has to be within that range.
Authors are encouraged to include a textual representation of
the gauge's state in the element's contents, for users of user
agents that do not support the meter
element.
The following examples show three gauges that would all be three-quarters full:
Storage space usage: <meter value=6 max=8>6 blocks used (out of 8 total)</meter> Voter turnout: <meter value=0.75><img alt="75%" src="graph75.png"></meter> Tickets sold: <meter min="0" max="100" value="75"></meter>
The following example is incorrect use of the element, because it doesn't give a range (and since the default maximum is 1, both of the gauges would end up looking maxed out):
<p>The grapefruit pie had a radius of <meter value=12>12cm</meter> and a height of <meter value=2>2cm</meter>.</p> <!-- BAD! -->
Instead, one would either not include the meter element, or use the meter element with a defined range to give the dimensions in context compared to other pies:
<p>The grapefruit pie had a radius of 12cm and a height of 2cm.</p> <dl> <dt>Radius: <dd> <meter min=0 max=20 value=12>12cm</meter> <dt>Height: <dd> <meter min=0 max=10 value=2>2cm</meter> </dl>
There is no explicit way to specify units in the meter
element, but the units may be
specified in the title
attribute in free-form text.
The example above could be extended to mention the units:
<dl> <dt>Radius: <dd> <meter min=0 max=20 value=12 title="centimeters">12cm</meter> <dt>Height: <dd> <meter min=0 max=10 value=2 title="centimeters">2cm</meter> </dl>
The following markup:
<h3>Suggested groups</h3> <menu type="toolbar"> <a href="?cmd=hsg" onclick="hideSuggestedGroups()">Hide suggested groups</a> </menu> <ul> <li> <p><a href="/group/comp.infosystems.www.authoring.stylesheets/view">comp.infosystems.www.authoring.stylesheets</a> - <a href="/group/comp.infosystems.www.authoring.stylesheets/subscribe">join</a></p> <p>Group description: <strong>Layout/presentation on the WWW.</strong></p> <p><meter value="0.5">Moderate activity,</meter> Usenet, 618 subscribers</p> </li> <li> <p><a href="/group/netscape.public.mozilla.xpinstall/view">netscape.public.mozilla.xpinstall</a> - <a href="/group/netscape.public.mozilla.xpinstall/subscribe">join</a></p> <p>Group description: <strong>Mozilla XPInstall discussion.</strong></p> <p><meter value="0.25">Low activity,</meter> Usenet, 22 subscribers</p> </li> <li> <p><a href="/group/mozilla.dev.general/view">mozilla.dev.general</a> - <a href="/group/mozilla.dev.general/subscribe">join</a></p> <p><meter value="0.25">Low activity,</meter> Usenet, 66 subscribers</p> </li> </ul>
Might be rendered as follows:
User agents combine the value of the title
attribute and the other attributes to
provide context-sensitive help or inline text detailing the actual
values.
For example, the following snippet:
<meter min=0 max=60 value=23.2 title=seconds></meter>
...might cause the user agent to display a gauge with a tooltip saying "Value: 23.2 out of 60." on one line and "seconds" on a second line.
The following example shows how a gauge could fall back to localized or pretty-printed text.
<p>Disk usage: <meter min=0 value=170261928 max=233257824>170 261 928 bytes used out of 233 257 824 bytes available</meter></p>