/d3plus-text

A smart SVG text box with line wrapping and automatic font size scaling.

Primary LanguageJavaScriptMIT LicenseMIT

d3plus-text

A smart SVG text box with line wrapping and automatic font size scaling.

Installing

If using npm, npm install d3plus-text. Otherwise, you can download the latest release from GitHub or load from a CDN.

import modules from "d3plus-text";

d3plus-text can be loaded as a standalone library or bundled as part of D3plus. ES modules, AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3plus global is exported:

<script src="https://cdn.jsdelivr.net/npm/d3plus-text@1"></script>
<script>
  console.log(d3plus);
</script>

Examples

Live examples can be found on d3plus.org, which includes a collection of example visualizations using d3plus-react. These examples are powered by the d3plus-storybook repo, and PRs are always welcome. 🍻

API Reference

  • fontExists - Given either a single font-family or a list of fonts, returns the name of the first font that can be rendered, or false if none are installed on the user's machine.
  • rtl - Returns true if the or element has either the "dir" HTML attribute or the "direction" CSS property set to "rtl". Accepts an optional DOM element as an argument, whose own inherited state will be evaluated rather than the default html/body logic.
  • stringify - Coerces value into a String.
  • strip - Removes all non ASCII characters from a string.
  • textSplit - Splits a given sentence into an array of words.
  • htmlDecode - Strips HTML and "un-escapes" escape characters.
  • textWidth - Given a text string, returns the predicted pixel width of the string when placed into DOM.
  • textWrap - Based on the defined styles and dimensions, breaks a string into an array of strings for each line of text.
  • titleCase - Capitalizes the first letter of each word in a phrase/sentence.
  • trim - Cross-browser implementation of trim.
  • trimLeft - Cross-browser implementation of trimLeft.
  • trimRight - Cross-browser implementation of trimRight.

TextBox <>

This is a global class, and extends all of the methods and functionality of BaseClass.

# new TextBox()

Creates a wrapped text box for each point in an array of data. See this example for help getting started using the TextBox class.

# TextBox.render([callback]) <>

Renders the text boxes. If a callback is specified, it will be called once the shapes are done drawing.

This is a static method of TextBox.

# TextBox.ariaHidden(value) <>

If value is specified, sets the aria-hidden attribute to the specified function or string and returns the current class instance.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.data([data]) <>

Sets the data array to the specified array. A text box will be drawn for each object in the array.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.delay([value]) <>

Sets the animation delay to the specified number in milliseconds.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.duration([value]) <>

Sets the animation duration to the specified number in milliseconds.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.ellipsis([value]) <>

Sets the function that handles what to do when a line is truncated. It should return the new value for the line, and is passed 2 arguments: the String of text for the line in question, and the number of the line. By default, an ellipsis is added to the end of any line except if it is the first word that cannot fit (in that case, an empty string is returned).

This is a static method of TextBox, and is chainable with other methods of this Class. default accessor

function(text, line) {
  return line ? text.replace(/\.|,$/g, "") + "..." : "";
}

# TextBox.fontColor([value]) <>

Sets the font color to the specified accessor function or static string, which is inferred from the DOM selection by default.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontFamily([value]) <>

Defines the font-family to be used. The value passed can be either a String name of a font, a comma-separated list of font-family fallbacks, an Array of fallbacks, or a Function that returns either a String or an Array. If supplying multiple fallback fonts, the fontExists function will be used to determine the first available font on the client's machine.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontMax([value]) <>

Sets the maximum font size to the specified accessor function or static number (which corresponds to pixel units), which is used when dynamically resizing fonts.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontMin([value]) <>

Sets the minimum font size to the specified accessor function or static number (which corresponds to pixel units), which is used when dynamically resizing fonts.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontOpacity([value]) <>

Sets the font opacity to the specified accessor function or static number between 0 and 1.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontResize([value]) <>

Toggles font resizing, which can either be defined as a static boolean for all data points, or an accessor function that returns a boolean. See this example for a side-by-side comparison.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontSize([value]) <>

Sets the font size to the specified accessor function or static number (which corresponds to pixel units), which is inferred from the DOM selection by default.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontStroke([value]) <>

Sets the font stroke color for the rendered text.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontStrokeWidth([value]) <>

Sets the font stroke width for the rendered text.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.fontWeight([value]) <>

Sets the font weight to the specified accessor function or static number, which is inferred from the DOM selection by default.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.height([value]) <>

Sets the height for each box to the specified accessor function or static number.

This is a static method of TextBox, and is chainable with other methods of this Class. default accessor

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

# TextBox.html([value = { i: 'font-style: italic;', em: 'font-style: italic;', b: 'font-weight: bold;', strong: 'font-weight: bold;' }]) <>

Configures the ability to render simple HTML tags. Defaults to supporting <b>, <strong>, <i>, and <em>, set to false to disable or provide a mapping of tags to svg styles

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.id([value]) <>

Defines the unique id for each box to the specified accessor function or static number.

This is a static method of TextBox, and is chainable with other methods of this Class. default accessor

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

# TextBox.lineHeight([value]) <>

Sets the line height to the specified accessor function or static number, which is 1.2 times the font size by default.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.maxLines([value]) <>

Restricts the maximum number of lines to wrap onto, which is null (unlimited) by default.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.overflow([value]) <>

Sets the text overflow to the specified accessor function or static boolean.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.padding([value]) <>

Sets the padding to the specified accessor function, CSS shorthand string, or static number, which is 0 by default.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.pointerEvents([value]) <>

Sets the pointer-events to the specified accessor function or static string.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.rotate([value]) <>

Sets the rotate percentage for each box to the specified accessor function or static string.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.rotateAnchor(_) <>

Sets the anchor point around which to rotate the text box.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.select([selector]) <>

Sets the SVG container element to the specified d3 selector or DOM element. If not explicitly specified, an SVG element will be added to the page for use.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.split([value]) <>

Sets the word split behavior to the specified function, which when passed a string is expected to return that string split into an array of words.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.text([value]) <>

Sets the text for each box to the specified accessor function or static string.

This is a static method of TextBox, and is chainable with other methods of this Class. default accessor

function(d) {
  return d.text;
}

# TextBox.textAnchor([value]) <>

Sets the horizontal text anchor to the specified accessor function or static string, whose values are analagous to the SVG text-anchor property.

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.verticalAlign([value]) <>

Sets the vertical alignment to the specified accessor function or static string. Accepts "top", "middle", and "bottom".

This is a static method of TextBox, and is chainable with other methods of this Class.

# TextBox.width([value]) <>

Sets the width for each box to the specified accessor function or static number.

This is a static method of TextBox, and is chainable with other methods of this Class. default accessor

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

# TextBox.x([value]) <>

Sets the x position for each box to the specified accessor function or static number. The number given should correspond to the left side of the textBox.

This is a static method of TextBox, and is chainable with other methods of this Class. default accessor

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

# TextBox.y([value]) <>

Sets the y position for each box to the specified accessor function or static number. The number given should correspond to the top side of the textBox.

This is a static method of TextBox, and is chainable with other methods of this Class. default accessor

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

d3plus.fontExists(font) <>

Given either a single font-family or a list of fonts, returns the name of the first font that can be rendered, or false if none are installed on the user's machine.

This is a global function.

d3plus.rtl([elem]) <>

Returns true if the or element has either the "dir" HTML attribute or the "direction" CSS property set to "rtl". Accepts an optional DOM element as an argument, whose own inherited state will be evaluated rather than the default html/body logic.

This is a global function.

d3plus.stringify(value) <>

Coerces value into a String.

This is a global function.

d3plus.strip(value, [spacer]) <>

Removes all non ASCII characters from a string.

This is a global function.

Param Type Default Description
value String
[spacer] String "-" The character(s) to be used in place of spaces.

d3plus.textSplit(sentence) <>

Splits a given sentence into an array of words.

This is a global function.

d3plus.htmlDecode(input) <>

Strips HTML and "un-escapes" escape characters.

This is a global function.

d3plus.textWidth(text, [style]) <>

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

This is a 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.

d3plus.textWrap() <>

Based on the defined styles and dimensions, breaks a string into an array of strings for each line of text.

This is a global function.

# d3plus..fontFamily([value]) <>

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

This is a static method of textWrap.

# d3plus..fontSize([value]) <>

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

This is a static method of textWrap.

# d3plus..fontWeight([value]) <>

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

This is a static method of textWrap.

# d3plus..height([value]) <>

If value is specified, sets height limit to the specified value and returns this generator. If value is not specified, returns the current value.

This is a static method of textWrap.

# d3plus..lineHeight([value]) <>

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

This is a static method of textWrap.

# d3plus..maxLines([value]) <>

If value is specified, sets the maximum number of lines allowed when wrapping.

This is a static method of textWrap.

# d3plus..overflow([value]) <>

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

This is a static method of textWrap.

# d3plus..split([value]) <>

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

This is a static method of textWrap.

# d3plus..width([value]) <>

If value is specified, sets width limit to the specified value and returns this generator. If value is not specified, returns the current value.

This is a static method of textWrap.

d3plus.titleCase(str) <>

Capitalizes the first letter of each word in a phrase/sentence.

This is a global function.

d3plus.trim(str) <>

Cross-browser implementation of trim.

This is a global function.

d3plus.trimLeft(str) <>

Cross-browser implementation of trimLeft.

This is a global function.

d3plus.trimRight(str) <>

Cross-browser implementation of trimRight.

This is a global function.

Documentation generated on Wed, 06 Mar 2024 16:14:10 GMT