TextBox

Creates a wrapped text box for each point in an array of data.

Basic example

Wraps three strings inside 200px-wide boxes: inline <i>, <u>, and <b> tags render as styled SVG, while the Chinese and Burmese lines show wrapping still works for scripts that don’t separate words with spaces.

const config = {
  data: [
    {
      text: "Here is text rendered in <i>SVG</i> that is <u>wrapped</u> and contains <b>HTML</b> tags.",
    },
    {text: "这是句子 2。即使包装器中没有空格，它也有效！"},
    {
      text: "၎င်းသည် ချိတ်ဆက်ထားသော စာလုံးများပင်လျှင် ဘာသာစကားအများစုတွင် အလုပ်လုပ်သည်။",
    },
  ],
  duration: 500,
  fontSize: 16,
  height: 200,
  lineHeight: 18,
  text: d => d.text,
  width: 200,
  x: (d, i) => i * (200 + 50),
};

Font resize

Three equally-sized boxes hold text of very different lengths. With fontResize: true each string is scaled between fontMin and fontMax to fill its box — the single word is sized way up while the long passage shrinks to fit. Toggle fontResize off in the controls to see them all snap back to one fixed size.

const config = {
  data: [
    {text: "Big"},
    {text: "A medium-length caption"},
    {
      text: "A much longer passage of text that has to shrink down so every word still fits inside the very same box",
    },
  ],
  fontResize: true,
  fontMax: 96,
  fontMin: 6,
  height: 180,
  text: d => d.text,
  width: 200,
  x: (d, i) => i * (200 + 50),
};

Alignment

textAnchor aligns the wrapped lines horizontally within the box (start, middle, or end) and verticalAlign places the block at the top, middle, or bottom of its height; both accept accessors, so each datum here chooses its own.

const config = {
  data: [
    {text: "textAnchor: start", anchor: "start", valign: "top"},
    {text: "textAnchor: middle", anchor: "middle", valign: "middle"},
    {text: "textAnchor: end", anchor: "end", valign: "bottom"},
  ],
  fontSize: 16,
  height: 150,
  text: d => d.text,
  textAnchor: d => d.anchor,
  verticalAlign: d => d.valign,
  width: 200,
  x: (d, i) => i * (200 + 50),
};

Rotation

rotate turns the whole box by that many degrees around rotateAnchor (its center by default), the same mechanism axes use for slanted tick labels and charts use for vertical bar labels.

const config = {
  data: [
    {text: "rotate: -45", rotate: -45},
    {text: "rotate: 0", rotate: 0},
    {text: "rotate: 90", rotate: 90},
  ],
  fontSize: 16,
  height: 60,
  rotate: d => d.rotate,
  text: d => d.text,
  width: 140,
  x: (d, i) => 60 + i * 220,
  y: 80,
};

Truncation

Text that does not fit is cut at the last whole line that fits the height, and maxLines caps the line count regardless of height. The cut line is passed through ellipsis, a function (text, line) => string that appends … by default and can be replaced to end truncated text any other way.

const long =
  "This passage is much longer than the two lines its box allows, so the wrapper has to decide what to do with the remainder.";

const config = {
  data: [
    {text: `height: 48 — ${long}`, maxLines: null},
    {text: `maxLines: 1 — ${long}`, maxLines: 1},
  ],
  fontSize: 15,
  height: 48,
  maxLines: d => d.maxLines,
  text: d => d.text,
  width: 240,
  x: (d, i) => i * (240 + 40),
};

Long words

A single word wider than the box cannot be wrapped. By default the wrapper stops there and truncates; overflow: true lets the word run past the box’s right edge instead, so nothing is lost when the box is only a sizing hint.

const config = {
  data: [
    {text: "overflow: false ABCDEFGHIJKLMNOPQRSTUVWXYZ", overflow: false},
    {text: "overflow: true ABCDEFGHIJKLMNOPQRSTUVWXYZ", overflow: true},
  ],
  fontSize: 16,
  height: 80,
  overflow: d => d.overflow,
  text: d => d.text,
  width: 150,
  x: (d, i) => i * (150 + 120),
};

Font styling

fontFamily, fontWeight, fontColor, and fontStroke/fontStrokeWidth all take values or accessors. A thin dark stroke around light text is how chart labels stay legible over any fill.

const config = {
  data: [
    {
      text: "Georgia, bold, slate",
      family: "Georgia, serif",
      weight: 700,
      color: "#495057",
    },
    {
      text: "Inter, regular, blue",
      family: "Inter, sans-serif",
      weight: 400,
      color: "#1c7ed6",
    },
    {
      text: "Monospace with a stroke",
      family: "ui-monospace, monospace",
      weight: 600,
      color: "#fff",
    },
  ],
  fontColor: d => d.color,
  fontFamily: d => d.family,
  fontSize: 18,
  fontStroke: d => (d.weight === 600 ? "#212529" : "none"),
  fontStrokeWidth: 1,
  fontWeight: d => d.weight,
  height: 80,
  text: d => d.text,
  width: 200,
  x: (d, i) => i * (200 + 50),
};

Configuration

import {TextBox} from "@d3plus/core";

Extends BaseClass.

Filter 12 config keys

classNamestring | array.<string> | undefined: CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.
colorDefaultscolordefaultsconfig: Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.
configd3plusconfig: Methods that correspond to the key/value pairs and returns this class.
dataarray.<datapoint>: The data array used to draw text boxes. A text box will be drawn for each object in the array.
htmlboolean | record: 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
localestring | object: The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.
onstring: Event listener for the specified event typenames. Mirrors the core d3-selection behavior.
parentunknown: Parent config used by the wrapper.
renderfunction: Renders the text boxes. If a callback is specified, it will be called once the shapes are done drawing.
selectstring | htmlelement: The SVG container element as a d3 selector or DOM element. If not specified, an SVG element will be added to the page.
shapeConfigd3plusconfig: Configuration object with key/value pairs applied as method calls on each shape.
translatefunction: Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.