Source: https://d3js.org/d3-shape/symbol

Skip to content

Return to top

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.

js

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.

js

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.

js

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.

js

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.

js

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

The symbol type accessor defaults to:

js

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.

js

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.

js

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.

js

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

The size accessor defaults to:

js

function size() {
  return 64;
}

symbol.context(context) ​

---

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

js

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

If context is not specified, returns the current context.

js

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.

js

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

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

js

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 ​

---

circlecrossdiamondsquarestartrianglewye

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 .

js

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

symbolsStroke ​

---

asteriskcirclediamond2plussquare2timestriangle2

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 .

js

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.

js

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.

js

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