W3cubDocs

/Web APIs

SVGLength

SVG length interface

The SVGLength interface correspond to the <length> basic data type.

An SVGLength object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown.

Interface overview

Also implement	None
Methods	`void newValueSpecifiedUnits(in unsigned short unitType, in float valueInSpecifiedUnits)` `void convertToSpecifiedUnits(in unsigned short unitType)`
Properties	readonly unsigned short `unitType` float `value` float `valueInSpecifiedUnits` string `valueAsString`
Constants	`SVG_LENGTHTYPE_UNKNOWN` = `0` `SVG_LENGTHTYPE_NUMBER` = `1` `SVG_LENGTHTYPE_PERCENTAGE` = `2` `SVG_LENGTHTYPE_EMS` = `3` `SVG_LENGTHTYPE_EXS` = `4` `SVG_LENGTHTYPE_PX` = `5` `SVG_LENGTHTYPE_CM` = `6` `SVG_LENGTHTYPE_MM` = `7` `SVG_LENGTHTYPE_IN` = `8` `SVG_LENGTHTYPE_PT` = `9` `SVG_LENGTHTYPE_PC` = `10`
Normative document	SVG 1.1 (2nd Edition)

Example

xml

<svg height="200" onload="start();" version="1.1" width="200" xmlns="http://www.w3.org/2000/svg">
  <script><![CDATA[
function start() {
  const rect = document.getElementById("myRect");
  const val  = rect.x.baseVal;

  // read x in pixel and cm units
  console.log("value: " + val.value +
            ", valueInSpecifiedUnits: " + val.unitType + ": " + val.valueInSpecifiedUnits +
            ", valueAsString: " + val.valueAsString);

  // set x = 20pt and read it out in pixel and pt units
  val.newValueSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_PT, 20);
  console.log("value: " + val.value +
            ", valueInSpecifiedUnits " + val.unitType + ": " + val.valueInSpecifiedUnits +
            ", valueAsString: " + val.valueAsString);

  // convert x = 20pt to inches and read out in pixel and inch units
  val.convertToSpecifiedUnits(SVGLength.SVG_LENGTHTYPE_IN);
  console.log("value: " + val.value +
            ", valueInSpecifiedUnits " + val.unitType + ": " + val.valueInSpecifiedUnits +
            ", valueAsString: " + val.valueAsString);
}
]]></script>
  <rect id="myRect"
        x="1cm" y="1cm"
        fill="green" stroke="black" stroke-width="1"
        width="1cm" height="1cm"
  />
</svg>

Results on a desktop monitor (pixel units will be dpi-dependent):

value: 37.7952766418457, valueInSpecifiedUnits: 6: 1, valueAsString: 1cm
value: 26.66666603088379, valueInSpecifiedUnits 9: 20, valueAsString: 20pt
value: 26.66666603088379, valueInSpecifiedUnits 8: 0.277777761220932, valueAsString: 0.277778in

Constants

Name	Value	Description
`SVG_LENGTHTYPE_UNKNOWN`	`0`	The unit type is not one of predefined unit types. It is invalid to attempt to define a new value of this type or to attempt to switch an existing value to this type.
`SVG_LENGTHTYPE_NUMBER`	`1`	No unit type was provided (i.e., a unitless value was specified), which indicates a value in user units.
`SVG_LENGTHTYPE_PERCENTAGE`	`2`	A percentage value was specified.
`SVG_LENGTHTYPE_EMS`	`3`	A value was specified using the em units defined in CSS2.
`SVG_LENGTHTYPE_EXS`	`4`	A value was specified using the ex units defined in CSS2.
`SVG_LENGTHTYPE_PX`	`5`	A value was specified using the px units defined in CSS2.
`SVG_LENGTHTYPE_CM`	`6`	A value was specified using the cm units defined in CSS2.
`SVG_LENGTHTYPE_MM`	`7`	A value was specified using the mm units defined in CSS2.
`SVG_LENGTHTYPE_IN`	`8`	A value was specified using the in units defined in CSS2.
`SVG_LENGTHTYPE_PT`	`9`	A value was specified using the pt units defined in CSS2.
`SVG_LENGTHTYPE_PC`	`10`	A value was specified using the pc units defined in CSS2.

Instance properties

Name	Type	Description
`unitType`	unsigned short	The type of the value as specified by one of the `SVG_LENGTHTYPE_*` constants defined on this interface.
`value`	float	The value as a floating point value, in user units. Setting this attribute will cause `valueInSpecifiedUnits` and `valueAsString` to be updated automatically to reflect this setting. Exceptions on setting: a `DOMException` with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read only attribute or when the object itself is read only.
`valueInSpecifiedUnits`	float	The value as a floating point value, in the units expressed by `unitType`. Setting this attribute will cause `value` and `valueAsString` to be updated automatically to reflect this setting. Exceptions on setting: a `DOMException` with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read only attribute or when the object itself is read only.
`valueAsString`	string	The value as a string value, in the units expressed by `unitType`. Setting this attribute will cause `value`, `valueInSpecifiedUnits`, and `unitType` to be updated automatically to reflect this setting. Exceptions on setting: a `DOMException` with code `SYNTAX_ERR` is raised if the assigned string cannot be parsed as a valid <length>. a `DOMException` with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read only attribute or when the object itself is read only.

Instance methods

Name & Arguments Return Description

Name & Arguments	Return	Description
`newValueSpecifiedUnits(in unsigned short unitType, in float valueInSpecifiedUnits)`	`void`	Reset the value as a number with an associated unitType, thereby replacing the values for all of the attributes on the object. Exceptions: a `DOMException` with code `NOT_SUPPORTED_ERR` is raised if `unitType` is `SVG_LENGTHTYPE_UNKNOWN` or not a valid unit type constant (one of the other `SVG_LENGTHTYPE_*` constants defined on this interface). a `DOMException` with code `NO_MODIFICATION_ALLOWED_ERR` is raised when the length corresponds to a read only attribute or when the object itself is read only.
`convertToSpecifiedUnits(in unsigned short unitType)`	`void`	Preserve the same underlying stored value, but reset the stored unit identifier to the given `unitType`. Object attributes `unitType`, `valueInSpecifiedUnits`, and `valueAsString` might be modified as a result of this method. For example, if the original value were `"0.5cm"` and the method was invoked to convert to millimeters, then the `unitType` would be changed to `SVG_LENGTHTYPE_MM`, `valueInSpecifiedUnits` would be changed to the numeric value `5` and `valueAsString` would be changed to `"5mm"`.

newValueSpecifiedUnits(in unsigned short
unitType, in float valueInSpecifiedUnits)

void

Reset the value as a number with an associated unitType, thereby replacing the values for all of the attributes on the object.

Exceptions:

a DOMException with code NOT_SUPPORTED_ERR is raised if unitType is SVG_LENGTHTYPE_UNKNOWN or not a valid unit type constant (one of the other SVG_LENGTHTYPE_* constants defined on this interface).
a DOMException with code NO_MODIFICATION_ALLOWED_ERR is raised when the length corresponds to a read only attribute or when the object itself is read only.

convertToSpecifiedUnits(in unsigned short unitType) void Preserve the same underlying stored value, but reset the stored unit identifier to the given unitType. Object attributes unitType, valueInSpecifiedUnits, and valueAsString might be modified as a result of this method. For example, if the original value were "0.5cm" and the method was invoked to convert to millimeters, then the unitType would be changed to SVG_LENGTHTYPE_MM, valueInSpecifiedUnits would be changed to the numeric value 5 and valueAsString would be changed to "5mm".

Browser compatibility

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	WebView Android	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet
`SVGLength`	1	12	1.5	9	≤12.1	3	≤37	18	4	≤12.1	1	1.0
`convertToSpecifiedUnits`	1	12	1.5	9	≤12.1	3	≤37	18	4	≤12.1	1	1.0
`newValueSpecifiedUnits`	1	12	1.5	9	≤12.1	3	≤37	18	4	≤12.1	1	1.0
`unitType`	1	12	1.5	9	≤12.1	3	≤37	18	4	≤12.1	1	1.0
`value`	1	12	1.5	9	≤12.1	3	≤37	18	4	≤12.1	1	1.0
`valueAsString`	1	12	1.5	9	≤12.1	3	≤37	18	4	≤12.1	1	1.0
`valueInSpecifiedUnits`	1	12	1.5	9	≤12.1	3	≤37	18	4	≤12.1	1	1.0

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/SVGLength