Basic Shapes — SVG 2

Mathematically, these shape elements are equivalent to a ‘path’ element that would construct the same shape. The basic shapes may be stroked, filled and used as clip paths. All of the properties available for ‘path’ elements also apply to the basic shapes.

The equivalent path and algorithm to compute the stroke for each shape are defined in the shape sections below.

9.2. The ‘rect’ element

The ‘rect’ element defines a rectangle which is axis-aligned with the current local coordinate system. Rounded rectangles can be achieved by setting appropriate values for attributes ‘rx’ and ‘ry’.

The ‘x’ and ‘y’ coordinates refer to the left and top edges of the rectangle, in the current user coordinate system.

The ‘width’ and ‘height’ of the rectangle. A negative value for either attribute is an error (see Error processing). A value of zero for either attribute disables rendering of the element.

For rounded rectangles, the x- and y-axis radii of the ellipse used to round off the corners of the rectangle. A negative value for either attribute is an error (see Error processing).

The values used for the x- and y-axis rounded corner radii are determined implicitly if the ‘rx’ or ‘ry’ attributes (or both) are not specified, or are specified but with invalid values. The values are also subject to clamping so that the lengths of the straight segments of the rectangle are never negative. The effective values for ‘rx’ and ‘ry’ are determined by following these steps in order:

Mathematically, a ‘rect’ element is mapped to an equivalent ‘path’ element as follows: (Note: all coordinate and length values are first converted into local coordinate system coordinates according to Units.)

Example rect01 shows a rectangle with sharp corners. The ‘rect’ element is filled with yellow and stroked with navy.

Example rect02 shows two rounded rectangles. The ‘rx’ specifies how to round the corners of the rectangles. Note that since no value has been specified for the ‘ry’ attribute, it will be assigned the same value as the ‘rx’ attribute.

9.3. The ‘circle’ element

The ‘cx’ and ‘cy’ attributes define the coordinates of the center of the circle.

The ‘r’ attribute defines the radius of the circle. A negative value is an error (see Error processing). A value of zero disables rendering of the element.

Mathematically, a ‘circle’ element is mapped to an equivalent ‘path’ element that consists of four elliptical arc segments, each covering a quarter of the circle. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformations).

Example circle01 consists of a ‘circle’ element that is filled with red and stroked with blue.

9.4. The ‘ellipse’ element

The ‘ellipse’ element defines an ellipse which is axis-aligned with the current local coordinate system based on a center point and two radii.

The ‘cx’ and ‘cy’ attributes define the x- and y-axis radii of the ellipse. A negative value for either attribute is an error (see Error processing). A value of zero disables rendering of the element.

Mathematically, an ‘ellipse’ element is mapped to an equivalent ‘path’ element that consists of four elliptical arc segments, each covering a quarter of the ellipse. The path begins at the "3 o'clock" point on the radius and proceeds in a clock-wise direction (before any transformation).

Example ellipse01 below specifies the coordinates of the two ellipses in the user coordinate system established by the ‘viewBox’ attribute on the ‘svg’ element and the ‘transform’ property on the ‘g’ and ‘ellipse’ elements. Both ellipses use the default values of zero for the ‘cx’ and ‘cy’ attributes (the center of the ellipse). The second ellipse is rotated.

9.5. The ‘line’ element

The ‘line’ element defines a line segment that starts at one point and ends at another.

Name	Value	Initial value	Animatable
x1, y1	<length> \| <percentage> \| <number>	0	yes

Name	Value	Initial value	Animatable
x2, y2	<length> \| <percentage> \| <number>	0	yes

Mathematically, a ‘line’ element can be mapped to an equivalent ‘path’ element as follows: (Note: all coordinate and length values are first converted into local coordinate system coordinates according to Units.)

Because ‘line’ elements are single lines and thus are geometrically one-dimensional, they have no interior; thus, ‘line’ elements are never filled (see the ‘fill’ property).

Example line01 below specifies the coordinates of the five lines in the user coordinate system established by the ‘viewBox’ attribute on the ‘svg’ element. The lines have different thicknesses.

9.6. The ‘polyline’ element

The ‘polyline’ element defines a set of connected straight line segments. Typically, ‘polyline’ elements define open shapes.

Name	Value	Initial value	Animatable
points	<points>	(none)	yes

Mathematically, a ‘polyline’ element can be mapped to an equivalent ‘path’ element as follows:

Example polyline01 below specifies a polyline in the user coordinate system established by the ‘viewBox’ attribute on the ‘svg’ element.

9.7. The ‘polygon’ element

The ‘polygon’ element defines a closed shape consisting of a set of connected straight line segments.

Name	Value	Initial value	Animatable
points	<points>	(none)	yes

Mathematically, a ‘polygon’ element can be mapped to an equivalent ‘path’ element as follows:

Example polygon01 below specifies two polygons (a star and a hexagon) in the user coordinate system established by the ‘viewBox’ attribute on the ‘svg’ element.

9.8. DOM interfaces

9.8.1. Interface SVGRectElement

An SVGRectElement object represents a ‘rect’ element in the DOM.

interface SVGRectElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength x;
  [SameObject] readonly attribute SVGAnimatedLength y;
  [SameObject] readonly attribute SVGAnimatedLength width;
  [SameObject] readonly attribute SVGAnimatedLength height;
  [SameObject] readonly attribute SVGAnimatedLength rx;
  [SameObject] readonly attribute SVGAnimatedLength ry;
};

The x, y, width, height, rx and ry IDL attributes reflect the computed values of the ‘x’, ‘y’, ‘width’, ‘height’, ‘rx’ and ‘ry’ properties and their corresponding presentation attributes, respectively.

9.8.2. Interface SVGCircleElement

An SVGCircleElement object represents a ‘circle’ element in the DOM.

interface SVGCircleElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength cx;
  [SameObject] readonly attribute SVGAnimatedLength cy;
  [SameObject] readonly attribute SVGAnimatedLength r;
};

The cx, cy and r IDL attributes reflect the computed values of the ‘cx’, ‘cy’ and ‘y’ properties and their corresponding presentation attributes, respectively.

9.8.3. Interface SVGEllipseElement

An SVGEllipseElement object represents a ‘ellipse’ element in the DOM.

interface SVGEllipseElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength cx;
  [SameObject] readonly attribute SVGAnimatedLength cy;
  [SameObject] readonly attribute SVGAnimatedLength rx;
  [SameObject] readonly attribute SVGAnimatedLength ry;
};

The cx, cy, rx and ry IDL attributes reflect the computed values of the ‘cx’, ‘cy’, ‘rx’ and ‘ry’ properties and their corresponding presentation attributes, respectively.

9.8.4. Interface SVGLineElement

The SVGLineElement interface corresponds to the ‘line’ element.

interface SVGLineElement : SVGGeometryElement {
  [SameObject] readonly attribute SVGAnimatedLength x1;
  [SameObject] readonly attribute SVGAnimatedLength y1;
  [SameObject] readonly attribute SVGAnimatedLength x2;
  [SameObject] readonly attribute SVGAnimatedLength y2;
};

The x1, y1, x2 and y2 IDL attributes reflect the ‘x1’, ‘y1’, ‘x2’ and ‘y2’ content attributes, respectively

9.8.5. Interface SVGAnimatedPoints

The SVGAnimatedPoints interface is used to reflect a ‘points’ attribute on a ‘polygon’ or ‘polyline’ element. It is mixed in to the SVGPolygonElement and SVGPolylineElement interfaces.

[NoInterfaceObject]
interface SVGAnimatedPoints {
  [SameObject] readonly attribute SVGPointList points;
  [SameObject] readonly attribute SVGPointList animatedPoints;
};

The points IDL attribute represents the current non-animated value of the reflected attribute. On getting points, an SVGPointList object is returned that reflects the base value of the reflected attribute.

The animatedPoints IDL attribute represents the current non-animated value of the reflected attribute. On getting animatedPoints, an SVGPointList object is returned that reflects the animated value of the reflected attribute.

The objects returned from points and animatedPoints must be distinct, even if there is no animation currently affecting the attribute.

9.8.6. Interface SVGPointList

The SVGPointList interface is a list interface whose elements are DOMPoint objects. An SVGPointList object represents a list of points.

interface SVGPointList {

  readonly attribute unsigned long length;
  readonly attribute unsigned long numberOfItems;

  void clear();
  DOMPoint initialize(DOMPoint newItem);
  getter DOMPoint getItem(unsigned long index);
  DOMPoint insertItemBefore(DOMPoint newItem, unsigned long index);
  DOMPoint replaceItem(DOMPoint newItem, unsigned long index);
  DOMPoint removeItem(unsigned long index);
  DOMPoint appendItem(DOMPoint newItem);
  setter void (unsigned long index, DOMPoint newItem);
};

The behavior of all of the interface members of SVGPointList are defined in List interfaces.

This specification imposes additional requirements on the behaviour of DOMPoint objects beyond those described in the the Geometry Interfaces specification, so that they can be used to reflect ‘points’ attributes.

Every DOMPoint object operates in one of four modes. It can:

reflect an element of the base value of a reflected animatable attribute (being exposed through the methods on the points member of an SVGAnimatedPoints),
reflect an element of the animated value of a reflected animatable attribute (being exposed through the methods on the animatedPoints member of an SVGAnimatedPoints),
represent the current translation of a given ‘svg’ element (being exposed through the currentTranslate member on SVGSVGElement), or
be detached, which is the case for DOMPoint objects created using their constructor or with createSVGPoint.

A DOMPoint object can be associated with a particular element. The associated element is used to determine which element's content attribute to update if the object reflects an attribute. Unless otherwise described, a DOMPoint object is not associated with any element.

A DOMPoint object can be designated as read only, which means that attempts to modify the object will result in an exception being thrown. When assigning to a read only DOMPoint's x, y, w or z IDL attribute, a DOMException with code NO_MODIFICATION_ALLOWED_ERR must be thrown instead of updating the internal coordinate value.

Note that this applies only to the read-write DOMPoint interface; the DOMPointReadOnly interface, which is not used for reflecting the ‘points’ attribute, will already throw an exception if an attempt is made to modify it.

When assigning to a writable DOMPoint's x, y, w or z IDL attribute, the following steps are run after updating the internal coordinate value:

If the DOMPoint reflects an element of the base value of a reflected attribute, then reserialize the reflected attribute using the SVGPointList that reflects the attribute's base value.
The DOMPoint can't reflect an element of the animated value, since it would be read only and we would have thrown an exception per the requirements above.
Otherwise, if the DOMPoint represents the current translation of an ‘svg’ element and that element is the outermost svg element, then:
1. Let [a b c d e f] be the 2x3 matrix that represents the document's magnification and panning transform.
2. Let x and y be the x and y coordinates of the DOMPoint object, respectively.
3. Set the document's magnification and panning transform to [a 0 0 d x y].

9.8.7. Interface SVGPolylineElement

An SVGPolylineElement object represents a ‘polyline’ element in the DOM.

interface SVGPolylineElement : SVGGeometryElement {
};

SVGPolylineElement implements SVGAnimatedPoints;

9.8.8. Interface SVGPolygonElement

An SVGPolygonElement object represents a ‘polygon’ element in the DOM.

interface SVGPolygonElement : SVGGeometryElement {
};

SVGPolygonElement implements SVGAnimatedPoints;

Chapter 9: Basic Shapes

Contents

9.1. Introduction and definitions