d3/docs/d3-shape/symbol.md

Symbols

Examples · Symbols provide a categorical shape encoding as in a scatterplot. Symbols are centered at the origin; use a transform to move the symbol to a different position.

symbol(type, size)

Source · Constructs a new symbol generator of the specified type and size. If not specified, type defaults to a circle, and size defaults to 64.

svg.append("path").attr("d", d3.symbol(d3.symbolCross));

symbol(...arguments)

Source · Generates a symbol for the given arguments. The arguments are arbitrary; they are propagated to the symbol generator’s accessor functions along with the this object. With the default settings, invoking the symbol generator produces a circle of 64 square pixels.

d3.symbol()() // "M4.514,0A4.514,4.514,0,1,1,-4.514,0A4.514,4.514,0,1,1,4.514,0"

If the symbol generator has a context, then the symbol is rendered to this context as a sequence of path method calls and this function returns void. Otherwise, a path data string is returned.

symbol.type(type)

Source · If type is specified, sets the symbol type to the specified function or symbol type and returns this symbol generator.

const symbol = d3.symbol().type(d3.symbolCross);

If type is a function, the symbol generator’s arguments and this are passed through. This is convenient for use with selection.attr, say in conjunction with an ordinal scale to produce a categorical symbol encoding.

const symbolType = d3.scaleOrdinal(d3.symbolsFill);
const symbol = d3.symbol().type((d) => symbolType(d.category));

If type is not specified, returns the current symbol type accessor.

symbol.type() // () => d3.symbolCross

The symbol type accessor defaults to:

function type() {
  return circle;
}

See symbolsFill and symbolsStroke for built-in symbol types. To implement a custom symbol type, pass an object that implements symbolType.draw.

symbol.size(size)

Source · If size is specified, sets the size to the specified function or number and returns this symbol generator.

const symbol = d3.symbol().size(100);

If size is a function, the symbol generator’s arguments and this are passed through. This is convenient for use with selection.attr, say in conjunction with a linear scale to produce a quantitative size encoding.

const symbolSize = d3.scaleLinear([0, 100]);
const symbol = d3.symbol().size((d) => symbolSize(d.value));

If size is not specified, returns the current size accessor.

symbol.size() // () => 100

The size accessor defaults to:

function size() {
  return 64;
}

symbol.context(context)

Source · If context is specified, sets the context and returns this symbol generator.

const context = canvas.getContext("2d");
const symbol = d3.symbol().context(context);

If context is not specified, returns the current context.

symbol.context() // context

The context defaults to null. If the context is not null, then the generated symbol is rendered to this context as a sequence of path method calls. Otherwise, a path data string representing the generated symbol is returned.

symbol.digits(digits)

Source · If digits is specified, sets the maximum number of digits after the decimal separator and returns this symbol generator.

const symbol = d3.symbol().digits(3);

If digits is not specified, returns the current maximum fraction digits, which defaults to 3.

symbol.digits() // 3

This option only applies when the associated context is null, as when this symbol generator is used to produce path data.

symbolsFill

Source · An array containing a set of symbol types designed for filling: circle, cross, diamond, square, star, triangle, and wye. Useful for a categorical shape encoding with an ordinal scale.

const symbolType = d3.scaleOrdinal(d3.symbolsFill);

symbolsStroke

Source · An array containing a set of symbol types designed for stroking: circle, plus, times, triangle2, asterisk, square2, and diamond2. Useful for a categorical shape encoding with an ordinal scale.

const symbolType = d3.scaleOrdinal(d3.symbolsStroke);

symbolAsterisk

Source · The asterisk symbol type; intended for stroking.

symbolCircle

Source · The circle symbol type; intended for either filling or stroking.

symbolCross

Source · The Greek cross symbol type, with arms of equal length; intended for filling.

symbolDiamond

Source · The rhombus symbol type; intended for filling.

symbolDiamond2

Source · The rotated square symbol type; intended for stroking.

symbolPlus

Source · The plus symbol type; intended for stroking.

symbolSquare

Source · The square symbol type; intended for filling.

symbolSquare2

Source · The square2 symbol type; intended for stroking.

symbolStar

Source · The pentagonal star (pentagram) symbol type; intended for filling.

symbolTriangle

Source · The up-pointing triangle symbol type; intended for filling.

symbolTriangle2

Source · The up-pointing triangle symbol type; intended for stroking.

symbolWye

Source · The Y-shape symbol type; intended for filling.

symbolTimes

Source · The X-shape symbol type; intended for stroking.

Custom symbols

Symbol types are typically not used directly, instead being passed to symbol.type. However, you can define your own symbol type implementation should none of the built-in types satisfy your needs using the following interface. You can also use this low-level interface with a built-in symbol type as an alternative to the symbol generator.

const path = d3.pathRound(3);
const circle = d3.symbolCircle.draw(path, 64);
path.toString(); // "M4.514,0A4.514,4.514,0,1,1,-4.514,0A4.514,4.514,0,1,1,4.514,0"

symbolType.draw(context, size)

Renders this symbol type to the specified context with the specified size in square pixels. The context implements the CanvasPathMethods interface. (Note that this is a subset of the CanvasRenderingContext2D interface!) See also d3-path.

pointRadial(angle, radius)

Examples · Source · Returns the point [x, y] for the given angle in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise, and the given radius.

d3.pointRadial(Math.PI / 3, 100) // [86.60254037844386, -50]