SVG Shapes

API Reference

SVG has a number of built-in simple shapes, such as axis-aligned rectangles and circles. For greater flexibility, you can use SVG's path element in conjunction with D3's path data generators. If you're familiar with Protovis, you'll note that D3's path generators are similar to Protovis marks.

SVG Elements

All SVG shapes can be transformed using the transform attribute. You can apply the transform either to the shape directly, or to a containing g element. Thus, when a shape is defined as "axis-aligned", that merely means axis-aligned within the local coordinate system; you can still rotate and otherwise transform the shape. Shapes can be filled and stroked using the fill and stroke styles. (You can also use the attributes of the same name, but styles are recommended as they are compatible with external stylesheets.)

# svg:rect x="0" y="0" width="0" height="0" rx="0" ry="0"

The rect element defines an axis-aligned rectangle. The top-left corner of the rectangle is positioned using the x and y attributes, while its size is specified using width and height. A rounded rectangle can be produced using the optional rx and ry attributes.

# svg:circle cx="0" cy="0" r="0"

The circle element defines a circle based on a center point and a radius. The center is positioned using the cx and cy attributes, while the radius is specified using the r attribute.

# svg:ellipse cx="0" cy="0" rx="0" ry="0"

The ellipse element defines an axis-aligned ellipse based on a center point and two radii. The center is positioned using the cx and cy attributes, while the radii are specified using the rx and ry attributes.

# svg:line x1="0" y1="0" x2="0" y2="0"

The line element defines a line segment that starts at one point and ends at another. The first point is specified using the x1 and x2 attributes, while the second point is specified using the x2 and y2 attributes. The line element is a popular choice for drawing rules, reference lines, axes and tick marks.

# svg:polyline points=""

The polyline element defines a set of connected straight line segments. Typically, polyline elements define open shapes. The points that make up the polyline are specified using the points attribute. Note: in D3, it is typically more convenient and flexible to use the d3.svg.line path generator in conjunction with a path element.

# svg:polygon points=""

The polygon element defines a closed shape consisting of a set of connected straight line segments. The points that make up the polygon are specified using the points attribute. Note: in D3, it is typically more convenient and flexible to use the d3.svg.line path generator in conjunction with a path element. The line can be closed using the closepath "Z" command.

# svg:text x="0" y="0" dx="0" dy="0" text-anchor="start"

The text element defines a graphics element consisting of text. The text content of the text element (see the text operator) define the characters to be rendered. The anchor position of the text element is controlled using the x and y attributes; additionally, the text can be offset from the anchor using dx and dy attributes. This offset is particularly convenient for controlling the text margin and baseline, as you can use "em" units which are relative to the font size. The horizontal text alignment is controlling using the text-anchor attribute. Here are a few examples:

<svg:text text-anchor="start">left-align, bottom-baseline</svg:text>
<svg:text text-anchor="middle">center-align, bottom-baseline</svg:text>
<svg:text text-anchor="end">right-align, bottom-baseline</svg:text>
<svg:text dy=".35em" text-anchor="start">left-align, middle-baseline</svg:text>
<svg:text dy=".35em" text-anchor="middle">center-align, middle-baseline</svg:text>
<svg:text dy=".35em" text-anchor="end">right-align, middle-baseline</svg:text>
<svg:text dy=".71em" text-anchor="start">left-align, top-baseline</svg:text>
<svg:text dy=".71em" text-anchor="middle">center-align, top-baseline</svg:text>
<svg:text dy=".71em" text-anchor="end">right-align, top-baseline</svg:text>

It's possible that there is a better way to specify the text baseline using SVG's baseline alignment properties, but these don't seem to be widely supported by browsers. Lastly, the font color is typically specified using the fill style (you can also use stroke), and the font is controlled using the font, font-family, font-size and related styles. Some browsers also support CSS3 properties, such as text-shadow.

# svg:path d="" transform=""

The path element represents the outline of a shape which can be filled, stroked, used as a clipping path, or any combination of the three. The d attribute defines the path data, which is a mini-language of path commands, such as moveto (M), lineto (L) and closepath (Z). The path element is a generalization of all other shapes in SVG, and can be used to draw nearly anything!

Path Data Generators

To simplify the construction of the d attribute for path elements, D3 includes a number of helper classes for generating path data. If you're familiar with Protovis, you'll find that these path generators are similar to Protovis mark types: each generator is a function of data. So, if you data is a sequence of xy coordinates, you can define accessor functions that the path generators use to produce path data. For example, you might define a line generator:

var line = d3.svg.line()
    .x(function(d) { return d.x; })
    .y(function(d) { return d.y; })
    .interpolate("basis");

Then later on, you can use this function to set the d attribute:

g.append("svg:path")
    .attr("d", line);

Whatever data is bound to g (in this example) will be passed to the line instance. Thus, the data must be specified as an array. For element element in the data array, the x- and y-accessor functions are used to pull out the control point coordinates.

A path generator, such as that returned by d3.svg.line, is both an object and a function. That is: you can call the generator like any other function, and the generator has additional methods that change its behavior. Like other classes in D3, path generators follow the method chaining pattern where setter methods return the generator itself, allowing multiple setters to be invoked in a concise statement.

# d3.svg.line()

Constructs a new line generator with the default x- and y-accessor functions (that assume the input data is a two-element array of numbers; see below for details), and linear interpolation. The input to the generator is always an array of data elements for which to generate a line. The output is a open piecewise linear curve, or polyline, as in a line chart:

By changing the interpolation, you can also generate splines and step functions. Also, don't be afraid to tack on additional path commands at the end. For example, if you want to generate a closed path, append a closepath (Z) command:

g.append("svg:path")
    .attr("d", function(d) { return line(d) + "Z"; });

The line generator is designed to work in conjunction with the area generator. For example, when producing an area chart, you might use an area generator with a fill style, and a line generator with a stroke style to emphasize the top edge of the area. Since the line generator is only used the set the d attribute, you can control the appearance of the line using standard SVG styles and attributes, such as fill, stroke and stroke-width.

# line.x([x])

If x is specified, sets the x-accessor to the specified function or constant. This accessor is invoked for each element in the data array passed to the line generator. The default accessor assumes that each input element is a two-element array of numbers:

function x(d) {
  return d[0];
}

Typically, an x-accessor is specified because the input data is in a different format, or because you want to apply a scale. For example, if your data is specified as an object with x and y attributes, rather than a tuple, you might dereference these attributes and apply the scales simultaneously:

var x = d3.scale.linear().range([0, w]),
    y = d3.scale.linear().range([0, h]);

var line = d3.svg.line()
    .x(function(d) { return x(d.x); })
    .y(function(d) { return y(d.y); });

The x-accessor is invoked in the same manner as other value functions in D3. The this context of the function is the current element in the selection. (Technically, the same this context that invokes the line function; however, in the common case that the line generator is passed to the attr operator, the this context will be the associated DOM element.) The function is passed two arguments, the current datum (d) and the current index (i). In this context, the index is the index into the array of control points, rather than the index of the current element in the selection. The x-accessor is invoked exactly once per datum, in the order specified by the data array. Thus, it is possible to specify a nondeterministic accessor, such as a random number generator. It is also possible to specify the x-accessor as a constant rather than a function, in which case all points will have the same x-coordinate.

If x is not specified, returns the current x-accessor.

# line.y([y])

If y is specified, sets the y-accessor to the specified function or constant. This accessor is invoked for each element in the data array passed to the line generator. The default accessor assumes that each input element is a two-element array of numbers:

function y(d) {
  return d[1];
}

For an example of how to specify a y-accessor, see the similiar x accessor. If y is not specified, returns the current y-accessor.

# line.interpolate([interpolate])

If interpolate is specified, sets the interpolation mode to the specified string. The following modes are supported:

• linear - piecewise linear segments, as in a polyline.
• step-before - alternate between vertical and horizontal segments, as in a step function.
• step-after - alternate between horizontal and vertical segments, as in a step function.
• basis - a B-spline, with control point duplication on the ends.
• basis-open - an open B-spline; may not intersect the start or end.
• basis-closed - a closed B-spline, as in a loop.
• cardinal - a Cardinal spline, with control point duplication on the ends.
• cardinal-open - an open Cardinal spline; may not intersect the start or end, but will intersect other control points.
• cardinal-closed - a closed Cardinal spline, as in a loop.
• monotone - cubic interpolation that preserves monotonicity in y.

The behavior of some of these interpolation modes may be further customized by specifying a tension.

If interpolate is not specified, returns the current interpolation mode.

# line.tension([tension])

If tension is specified, sets the Cardinal spline interpolation tension to the specified number in the range [0, 1]. The tension only affects the Cardinal interpolation modes: cardinal, cardinal-open and cardinal-closed. The default tension is 0.7. In some sense, this can be interpreted as the length of the tangent; 1 will yield all zero tangents, and 0 yields a Catmull-Rom spline. If tension is not specified, returns the current tension.

Note that the tension must be specified as a constant, rather than a function, as it is constant for the entirety of the line. However, it is still possible to generate multiple lines with different tensions using the same generator. For example:

svg.selectAll("path")
    .data([0, 0.2, 0.4, 0.6, 0.8, 1])
  .enter().append("svg:path")
    .attr("d", function(d) { return line.tension(d)(data); });

In this example (see the live version), the tension is set before each invocation of the line generator, thus resulting in lines with the same data but different paths.

# d3.svg.area()

# area.x([x])

# area.y0([y0])

# area.y1([y1])

# area.interpolate([interpolate])

# area.tension([tension])

# d3.svg.arc()

# arc.innerRadius([radius])

# arc.outerRadius([radius])

# arc.startAngle([angle])

# arc.endAngle([angle])

# arc.centroid()

# d3.svg.symbol()

# symbol.type([type])

# symbol.size([size])

# d3.svg.chord()

# chord.radius([radius])

# chord.startAngle([angle])

# chord.endAngle([angle])

# chord.source([source])

# chord.target([target])

# d3.svg.diagonal()

# diagonal.source([source])

# diagonal.target([target])