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.
Authoring
requirements: 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>
User agent requirements: User agents must parse
the min
, max
, value
, low
, high
, and optimum
attributes using the
rules for parsing floating-point number values.
User agents must then use all these numbers to obtain values for six points on the gauge, as follows. (The order in which these are evaluated is important, as some of the values refer to earlier ones.)
If the min
attribute is
specified and a value could be parsed out of it, then the minimum
value is that value. Otherwise, the minimum value is zero.
If the max
attribute is
specified and a value could be parsed out of it, then the
candidate maximum value is that value. Otherwise, the candidate
maximum value is 1.0.
If the candidate maximum value is greater than or equal to the minimum value, then the maximum value is the candidate maximum value. Otherwise, the maximum value is the same as the minimum value.
If the value
attribute is
specified and a value could be parsed out of it, then that value
is the candidate actual value. Otherwise, the candidate actual
value is zero.
If the candidate actual value is less than the minimum value, then the actual value is the minimum value.
Otherwise, if the candidate actual value is greater than the maximum value, then the actual value is the maximum value.
Otherwise, the actual value is the candidate actual value.
If the low
attribute is
specified and a value could be parsed out of it, then the
candidate low boundary is that value. Otherwise, the candidate low
boundary is the same as the minimum value.
If the candidate low boundary is less than the minimum value, then the low boundary is the minimum value.
Otherwise, if the candidate low boundary is greater than the maximum value, then the low boundary is the maximum value.
Otherwise, the low boundary is the candidate low boundary.
If the high
attribute is
specified and a value could be parsed out of it, then the
candidate high boundary is that value. Otherwise, the candidate
high boundary is the same as the maximum value.
If the candidate high boundary is less than the low boundary, then the high boundary is the low boundary.
Otherwise, if the candidate high boundary is greater than the maximum value, then the high boundary is the maximum value.
Otherwise, the high boundary is the candidate high boundary.
If the optimum
attribute is specified and a value could be parsed out of it, then
the candidate optimum point is that value. Otherwise, the
candidate optimum point is the midpoint between the minimum value
and the maximum value.
If the candidate optimum point is less than the minimum value, then the optimum point is the minimum value.
Otherwise, if the candidate optimum point is greater than the maximum value, then the optimum point is the maximum value.
Otherwise, the optimum point is the candidate optimum point.
All of which will result in the following inequalities all being true:
UA requirements for regions of the gauge: If the optimum point is equal to the low boundary or the high boundary, or anywhere in between them, then the region between the low and high boundaries of the gauge must be treated as the optimum region, and the low and high parts, if any, must be treated as suboptimal. Otherwise, if the optimum point is less than the low boundary, then the region between the minimum value and the low boundary must be treated as the optimum region, the region from the low boundary up to the high boundary must be treated as a suboptimal region, and the remaining region must be treated as an even less good region. Finally, if the optimum point is higher than the high boundary, then the situation is reversed; the region between the high boundary and the maximum value must be treated as the optimum region, the region from the high boundary down to the low boundary must be treated as a suboptimal region, and the remaining region must be treated as an even less good region.
UA requirements for showing the gauge: When
representing a meter
element to the user, the UA should
indicate the relative position of the actual value to the minimum
and maximum values, and the relationship between the actual value
and the three regions of the gauge.
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 may 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 value
IDL
attribute, on getting, must return the actual 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 min
IDL
attribute, on getting, must return the minimum value. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the min
content attribute must be set to
that string.
The max
IDL
attribute, on getting, must return the maximum value. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the max
content attribute must be set to
that string.
The low
IDL
attribute, on getting, must return the low boundary. On setting, the given
value must be converted to the best representation of the
number as a floating-point number and then the low
content attribute must be set to
that string.
The high
IDL
attribute, on getting, must return the high boundary. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the high
content attribute must be set to
that string.
The optimum
IDL
attribute, on getting, must return the optimum value. On setting, the
given value must be converted to the best representation of
the number as a floating-point number and then the optimum
content attribute must be
set to that string.
The labels
IDL attribute
provides a list of the element's label
s.
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>