d3plus-text

d3plus-text

A javascript library that contains various text functions, most notably SVG text wrapping with automatic font size scaling.

Installation Options

• NPM
• Browser
• AMD and CommonJS
• Custom Builds

NPM

npm install d3plus-text

Browser

In a vanilla environment, a d3plus_text global is exported. To use a compiled version hosted on d3plus.org that includes all dependencies:

<script src="https://d3plus.org/js/d3plus-text.v0.4.full.min.js"></script>

For development purposes, you can also load all dependencies separately:

<script src="https://d3js.org/d3-array.v0.7.min.js"></script>
<script src="https://d3js.org/d3-color.v0.4.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v0.4.min.js"></script>
<script src="https://d3js.org/d3-ease.v0.7.min.js"></script>
<script src="https://d3js.org/d3-interpolate.v0.7.min.js"></script>
<script src="https://d3js.org/d3-selection.v0.7.min.js"></script>
<script src="https://d3js.org/d3-timer.v0.4.min.js"></script>
<script src="https://d3js.org/d3-transition.v0.2.min.js"></script>
<script src="http://d3plus.org/js/d3plus-text.v0.4.min.js"></script>

Otherwise, click here to download the latest release.

AMD and CommonJS

The released bundle natively supports both AMD and CommonJS, and vanilla environments.

Custom Builds

The source code is written using standard import and export statements. Create a custom build using Rollup or your preferred bundler. Take a look at the index.js file to see the modules exported.

---

API Reference

Functions

box([data])

Creates a wrapped text box based on an array of data. If data is specified, immediately wraps the text based on the specified array and returns this box generator. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

width(text, [style])

Given a text string, returns the predicted pixel width of the string when placed into DOM.

box([data])

Creates a wrapped text box based on an array of data. If data is specified, immediately wraps the text based on the specified array and returns this box generator. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

Kind: global function

Param	Type	Default
[data]	Array	[]

Example (a sample row of data)

var data = {"text": "Hello D3plus, please wrap this sentence for me."};

Example (passed to the generator)

box([data]);

Example (creates the following)

<text class="d3plus-text-box" id="d3plus-text-box-0" text-anchor="start" font-family="Helvetica Neue" font-size="16px" transform="translate(0,-3.6)">
  <tspan dominant-baseline="alphabetic" opacity="1" x="0px" dx="0px" dy="18px" style="baseline-shift: 0%;">
    Hello D3plus, please wrap
  </tspan>
  <tspan dominant-baseline="alphabetic" opacity="1" x="0px" dx="0px" dy="18px" style="baseline-shift: 0%;">
    this sentence for me.
  </tspan>
</text>

Example (this is shorthand for the following)

box().data([data])();

Example (which also allows a post-draw callback function)

box().data([data])(function() { alert("draw complete!"); })

• box([data])
  • .data([data])
  • .delay([value])
  • .duration([value])
  • .ellipsis([value])
  • .fontColor([value])
  • .fontFamily([value])
  • .fontMax([value])
  • .fontMin([value])
  • .fontResize([value])
  • .fontSize([value])
  • .height([value])
  • .id([value])
  • .lineHeight([value])
  • .overflow([value])
  • .select([selector])
  • .split([value])
  • .text([value])
  • .textAnchor([value])
  • .verticalAlign([value])
  • .width([value])
  • .x([value])
  • .y([value])

box.data([data])

If data is specified, sets the data array to the specified array and returns this box generator. If data is not specified, returns the current data array. A text box will be drawn for each object in the array.

Kind: static method of box

Param	Type	Default
[data]	Array	[]

box.delay([value])

If value is specified, sets the animation delay to the specified number and returns this box generator. If value is not specified, returns the current animation delay.

Kind: static method of box

Param	Type	Default
[value]	Number	0

box.duration([value])

If value is specified, sets the animation duration to the specified number and returns this box generator. If value is not specified, returns the current animation duration.

Kind: static method of box

Param	Type	Default
[value]	Number	0

box.ellipsis([value])

If value is specified, sets the ellipsis method to the specified function or string and returns this box generator. If value is not specified, returns the current ellipsis method, which simply adds an ellipsis to the string by default.

Kind: static method of box

Param	Type
[value]	function | String

Example

function(d) {
  return d + "...";
}

box.fontColor([value])

If value is specified, sets the font color accessor to the specified function or string and returns this box generator. If value is not specified, returns the current font color accessor, which is inferred from the container element by default.

Kind: static method of box

Param	Type
[value]	function | String

box.fontFamily([value])

If value is specified, sets the font family accessor to the specified function or string and returns this box generator. If value is not specified, returns the current font family accessor, which is inferred from the container element by default.

Kind: static method of box

Param	Type
[value]	function | String

box.fontMax([value])

If value is specified, sets the maximum font size accessor to the specified function or number and returns this box generator. If value is not specified, returns the current maximum font size accessor. The maximum font size is used when resizing fonts dynamically.

Kind: static method of box

Param	Type	Default
[value]	function | Number	50

box.fontMin([value])

If value is specified, sets the minimum font size accessor to the specified function or number and returns this box generator. If value is not specified, returns the current minimum font size accessor. The minimum font size is used when resizing fonts dynamically.

Kind: static method of box

Param	Type	Default
[value]	function | Number	8

box.fontResize([value])

If value is specified, sets the font resizing accessor to the specified function or boolean and returns this box generator. If value is not specified, returns the current font resizing accessor.

Kind: static method of box

Param	Type	Default
[value]	function | Boolean	false

box.fontSize([value])

If value is specified, sets the font size accessor to the specified function or number and returns this box generator. If value is not specified, returns the current font size accessor, which is inferred from the container element by default.

Kind: static method of box

Param	Type
[value]	function | Number

box.height([value])

If value is specified, sets the height accessor to the specified function or number and returns this box generator. If value is not specified, returns the current height accessor.

Kind: static method of box

Param	Type
[value]	function | Number

Example

function(d) {
  return d.height || 200;
}

box.id([value])

If value is specified, sets the id accessor to the specified function or number and returns this box generator. If value is not specified, returns the current id accessor.

Kind: static method of box

Param	Type
[value]	function | Number

Example

function(d, i) {
  return d.id || i + "";
}

box.lineHeight([value])

If value is specified, sets the line height accessor to the specified function or number and returns this box generator. If value is not specified, returns the current line height accessor, which is 1.1 times the font size by default.

Kind: static method of box

Param	Type
[value]	function | Number

box.overflow([value])

If value is specified, sets the overflow accessor to the specified function or boolean and returns this box generator. If value is not specified, returns the current overflow accessor.

Kind: static method of box

Param	Type	Default
[value]	function | Boolean	false

box.select([selector])

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns this box generator. If selector is not specified, returns the current SVG container element, which adds an SVG element to the page by default.

Kind: static method of box

Param	Type
[selector]	String | HTMLElement

box.split([value])

If value is specified, sets the word split function to the specified function and returns this box generator. If value is not specified, returns the current word split function.

Kind: static method of box

Param	Type	Description
[value]	function	A function that, when passed a string, is expected to return that string split into an array of words to wrap. The default split function splits strings on the following characters: -, /, ;, :, &

box.text([value])

If value is specified, sets the text accessor to the specified function or string and returns this box generator. If value is not specified, returns the current text accessor.

Kind: static method of box

Param	Type
[value]	function | String

Example

function(d) {
  return d.text;
}

box.textAnchor([value])

If value is specified, sets the horizontal text anchor accessor to the specified function or string and returns this box generator. If value is not specified, returns the current horizontal text anchor accessor.

Kind: static method of box

Param	Type	Default	Description
[value]	function | String	"start"	Analagous to the SVG text-anchor property.

box.verticalAlign([value])

If value is specified, sets the vertical alignment accessor to the specified function or string and returns this box generator. If value is not specified, returns the current vertical alignment accessor.

Kind: static method of box

Param	Type	Default	Description
[value]	function | String	"top"	Accepts "top", "middle", and "bottom".

box.width([value])

If value is specified, sets the width accessor to the specified function or number and returns this box generator. If value is not specified, returns the current width accessor.

Kind: static method of box

Param	Type
[value]	function | Number

Example

function(d) {
  return d.width || 200;
}

box.x([value])

If value is specified, sets the x accessor to the specified function or number and returns this box generator. If value is not specified, returns the current x accessor. The number returned should correspond to the left position of the box.

Kind: static method of box

Param	Type
[value]	function | Number

Example

function(d) {
  return d.x || 0;
}

box.y([value])

If value is specified, sets the y accessor to the specified function or number and returns this box generator. If value is not specified, returns the current y accessor. The number returned should correspond to the top position of the box.

Kind: static method of box

Param	Type
[value]	function | Number

Example

function(d) {
  return d.y || 0;
}

width(text, [style])

Given a text string, returns the predicted pixel width of the string when placed into DOM.

Kind: global function

Param	Type	Description
text	String | Array	Can be either a single string or an array of strings to analyze.
[style]	Object	An object of CSS font styles to apply. Accepts any of the valid CSS font property values.