This is revision 1.5612.
A submittable element is a
candidate for constraint validation except when a
condition has barred
the element from constraint validation. (For example, an
element is barred from constraint validation if it is
an object
element.)
An element can have a custom validity error message
defined. Initially, an element must have its custom validity
error message set to the empty string. When its value is not
the empty string, the element is suffering from a custom
error. It can be set using the setCustomValidity()
method. The user agent should use the custom validity error
message when alerting the user to the problem with the
control.
An element can be constrained in various ways. The following is the list of validity states that a form control can be in, making the control invalid for the purposes of constraint validation. (The definitions below are non-normative; other parts of this specification define more precisely when each state applies or does not.)
When a control has no value but has a required
attribute (input
required
, select
required
,
textarea
required
), or, in the case of
an element in a radio button group, any of the other
elements in the group has a required
attribute.
When a control that allows arbitrary user input has a value that is not in the correct syntax (E-mail, URL).
When a control has a value that doesn't satisfy the
pattern
attribute.
When a control has a value that is too long for the
form control maxlength
attribute (input
maxlength
,
textarea
maxlength
).
When a control has a value that is too low for the min
attribute.
When a control has a value that is too high for the
max
attribute.
When a control has a value that doesn't fit the rules
given by the step
attribute.
When a control's custom validity error
message (as set by the element's setCustomValidity()
method) is not the empty string.
An element can still suffer from these states even when the element is disabled; thus these states can be represented in the DOM even if validating the form during submission wouldn't indicate a problem to the user.
An element satisfies its constraints if it is not suffering from any of the above validity states.
When the user agent is required to statically validate the
constraints of form
element form, it must run the following steps, which return
either a positive result (all the controls in the form are
valid) or a negative result (there are invalid controls)
along with a (possibly empty) list of elements that are invalid and
for which no script has claimed responsibility:
Let controls be a list of all the submittable elements whose form owner is form, in tree order.
Let invalid controls be an initially empty list of elements.
For each element field in controls, in tree order, run the following substeps:
If field is not a candidate for constraint validation, then move on to the next element.
Otherwise, if field satisfies its constraints, then move on to the next element.
Otherwise, add field to invalid controls.
If invalid controls is empty, then return a positive result and abort these steps.
Let unhandled invalid controls be an initially empty list of elements.
For each element field in invalid controls, if any, in tree order, run the following substeps:
Fire a simple event named invalid
that is cancelable at field.
If the event was not canceled, then add field to unhandled invalid controls.
Return a negative result with the list of elements in the unhandled invalid controls list.
If a user agent is to interactively validate the
constraints of form
element form, then the user agent must run the following
steps:
Statically validate the constraints of form, and let unhandled invalid controls be the list of elements returned if the result was negative.
If the result was positive, then return that result and abort these steps.
Report the problems with the constraints of at least one of
the elements given in unhandled invalid
controls to the user. User agents may focus one of those
elements in the process, by running the focusing steps
for that element, and may change the scrolling position of the
document, or perform some other action that brings the element to
the user's attention. User agents may report more than one
constraint violation. User agents may coalesce related constraint
violation reports if appropriate (e.g. if multiple radio buttons in
a group are marked as
required, only one error need be reported). If one of the controls
is not being rendered (e.g. it has the hidden
attribute set) then user agents
may report a script error.
Return a negative result.
willValidate
Returns true if the element will be validated when the form is submitted; false otherwise.
setCustomValidity
(message)Sets a custom error, so that the element would fail to validate. The given message is the message to be shown to the user when reporting the problem to the user.
If the argument is the empty string, clears the custom error.
validity
. valueMissing
Returns true if the element has no value but is a required field; false otherwise.
validity
. typeMismatch
Returns true if the element's value is not in the correct syntax; false otherwise.
validity
. patternMismatch
Returns true if the element's value doesn't match the provided pattern; false otherwise.
validity
. tooLong
Returns true if the element's value is longer than the provided maximum length; false otherwise.
validity
. rangeUnderflow
Returns true if the element's value is lower than the provided minimum; false otherwise.
validity
. rangeOverflow
Returns true if the element's value is higher than the provided maximum; false otherwise.
validity
. stepMismatch
Returns true if the element's value doesn't fit the rules given by the step
attribute; false otherwise.
validity
. customError
Returns true if the element has a custom error; false otherwise.
validity
. valid
Returns true if the element's value has no validity problems; false otherwise.
checkValidity
()Returns true if the element's value has no validity problems;
false otherwise. Fires an invalid
event at the element in the
latter case.
validationMessage
Returns the error message that would be shown to the user if the element was to be checked for validity.
The willValidate
attribute must return true if an element is a candidate for
constraint validation, and false otherwise (i.e. false if any
conditions are barring it from constraint validation).
The setCustomValidity(message)
, when invoked, must set the
custom validity error message to the value of the given
message argument.
In the following example, a script checks the value of a form
control each time it is edited, and whenever it is not a valid
value, uses the setCustomValidity()
method
to set an appropriate message.
<label>Feeling: <input name=f type="text" oninput="check(this)"></label> <script> function check(input) { if (input.value == "good" || input.value == "fine" || input.value == "tired") { input.setCustomValidity('"' + input.value + '" is not a feeling.'); } else { // input is fine -- reset the error message input.setCustomValidity(''); } } </script>
The validity
attribute must return a ValidityState
object that
represents the validity states of the element. This
object is live, and the same object must be returned
each time the element's validity
attribute is retrieved.
interface ValidityState { readonly attribute boolean valueMissing; readonly attribute boolean typeMismatch; readonly attribute boolean patternMismatch; readonly attribute boolean tooLong; readonly attribute boolean rangeUnderflow; readonly attribute boolean rangeOverflow; readonly attribute boolean stepMismatch; readonly attribute boolean customError; readonly attribute boolean valid; };
A ValidityState
object has the following
attributes. On getting, they must return true if the corresponding
condition given in the following list is true, and false
otherwise.
valueMissing
The control is suffering from being missing.
typeMismatch
The control is suffering from a type mismatch.
patternMismatch
The control is suffering from a pattern mismatch.
tooLong
The control is suffering from being too long.
rangeUnderflow
The control is suffering from an underflow.
rangeOverflow
The control is suffering from an overflow.
stepMismatch
The control is suffering from a step mismatch.
customError
The control is suffering from a custom error.
valid
None of the other conditions are true.
When the checkValidity()
method is invoked, if the element is a candidate for
constraint validation and does not satisfy its constraints, the user
agent must fire a simple event named invalid
that is cancelable (but in this
case has no default action) at the element and return
false. Otherwise, it must only return true without doing anything
else.
The validationMessage
attribute must return the empty string if the element is not a
candidate for constraint validation or if it is one but
it satisfies its constraints;
otherwise, it must return a suitably localized message that the user
agent would show the user if this were the only form control with a
validity constraint problem. If the user agent would not actually
show a textual message in such a situation (e.g. it would show a
graphical cue instead), then the attribute must return a suitably
localized message that expresses (one or more of) the validity
constraint(s) that the control does not satisfy. If the element is a
candidate for constraint validation and is
suffering from a custom error, then the custom
validity error message should be present in the return
value.
Servers should not rely on client-side validation. Client-side validation can be intentionally bypassed by hostile users, and unintentionally bypassed by users of older user agents or automated tools that do not implement these features. The constraint validation features are only intended to improve the user experience, not to provide any kind of security mechanism.