CSSNumericValue: equals() method
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Want more browser support for this feature? Tell us why.
Note: This feature is available in Web Workers.
The equals() method of the CSSNumericValue interface returns true if every value passed to it is the same as the CSSNumericValue, and false otherwise.
Syntax
equals()
equals(number1)
equals(number1, number2)
equals(number1, number2, /* …, */ numberN)
Parameters
number1, …,numberNOptional-
Either a number or a
CSSNumericValue. A number is converted to aCSSUnitValuewhose unit is"number", so2is treated asCSS.number(2).
Return value
true if every value passed is the same as the CSSNumericValue, and false otherwise.
If no values are passed, the method returns true.
The Description explains how this comparison works for single values, such as a CSSUnitValue, and for calculations, such as a CSSMathSum.
Exceptions
None.
Description
The method compares how the values are written, not what they compute to.
Single values, such as those represented by CSSUnitValue, are the same when they have the same value and unit.
Units aren't converted, so CSS.in(1) isn't the same as CSS.cm(2.54), even though both are one inch long.
Comparing values of different types, such as a length and a time, always returns false.
Calculations, such as sums represented by CSSMathSum, are the same when they are the same kind of calculation and contain the same values in the same order.
So a sum of 1px and 2px isn't the same as a sum of 2px and 1px, or as 3px.
This strict comparison is intentional, because checking that two values are written the same way is fast.
Examples
Comparing single values and sums
Values with the same value and unit are the same, and so are sums of the same values in the same order:
console.log(CSS.px(10).equals(CSS.px(10))); // true
const sum = new CSSMathSum(CSS.px(1), CSS.px(2));
console.log(sum.equals(new CSSMathSum(CSS.px(1), CSS.px(2)))); // true
The method returns false if the values in a sum are in a different order, if a sum is compared with the single value it adds up to, if the same length is written in a different unit, or if the values are different types:
console.log(sum.equals(new CSSMathSum(CSS.px(2), CSS.px(1)))); // false
console.log(sum.equals(CSS.px(3))); // false
console.log(CSS.in(1).equals(CSS.cm(2.54))); // false
console.log(CSS.px(1).equals(CSS.s(1))); // false
Comparing several values
When several values are passed, the method returns true only if each of them is the same as the CSSNumericValue.
In the first comparison below, the number 5 is converted to CSS.number(5), so both values are the same as the CSSNumericValue:
console.log(CSS.number(5).equals(5, CSS.number(5))); // true
console.log(CSS.px(10).equals(CSS.px(10), CSS.px(11))); // false
Specifications
| Specification |
|---|
| CSS Typed OM Level 1 # dom-cssnumericvalue-equals |