Attribute Coercion Behavior breaking
This is a low-level internal API change and does not affect most developers.
Here is a high level summary of the changes:
- Drop the internal concept of enumerated attributes and treat those attributes the same as normal non-boolean attributes
- BREAKING: No longer removes attribute if the value is boolean
false. Instead, it's set as attr="false". To remove the attribute, use
For more information, read on!
In 2.x, we had the following strategies for coercing
For some attribute/element pairs, Vue is always using the corresponding IDL attribute (property): like
For "boolean attributes" and xlinks, Vue removes them if they are "falsy" (
false) and adds them otherwise (see here and here).
For "enumerated attributes" (currently
spellcheck), Vue tries to coerce them to string (with special treatment for
contenteditablefor now, to fix vuejs/vue#9397).
For other attributes, we remove "falsy" values (
false) and set other values as-is (see here).
The following table describes how Vue coerce "enumerated attributes" differently with normal non-boolean attributes:
We can see from the table above, current implementation coerces
'true' but removes the attribute if it's
false. This also led to inconsistency and required users to manually coerce boolean values to string in very common use cases like
aria-* attributes like
We intend to drop this internal concept of "enumerated attributes" and treat them as normal non-boolean HTML attributes.
- This solves the inconsistency between normal non-boolean attributes and “enumerated attributes”
- It also makes it possible to use values other than
'false', or even keywords yet to come, for attributes like
For non-boolean attributes, Vue will stop removing them if they are
false and coerce them to
- This solves the inconsistency between
falseand makes outputting
The following table describes the new behavior:
Coercion for boolean attributes is left untouched.
The absence of an enumerated attribute and
attr="false" may produce different IDL attribute values (which will reflect the actual state), described as follows:
|Absent enumerated attr||IDL attr & value|
Since we no longer coerce
'false' for “enumerated properties” in 3.x, in the case of
spellcheck, developers will need to change those
v-bind expressions that used to resolve to
null to resolve to
'false' in order to maintain the same behavior as 2.x.
In 2.x, invalid values were coerced to
'true' for enumerated attributes. This was usually unintended and unlikely to be relied upon on a large scale. In 3.x
'true' should be explicitly specified.
'false' instead of removing the attribute
undefined should be used to explicitly remove an attribute.
Comparison between 2.x & 3.x behavior
|2.x “Enumerated attrs”|
|Other non-boolean attrs|