jointjs/docs/src/joint/api/util/breakText.html

JavaScript diagramming library

<pre class="docs-method-signature"><code>util.breakText(text, size [, attrs, opt])</code></pre>
<p>Break the provided <code>text</code> into lines so that it can fit into the bounding box defined by <code>size.width</code> and (optionally) <code>size.height</code>.</p>

<p>The function creates a temporary SVG <code>&lt;text&gt;</code> element and adds words to it one by one, measuring the element's actual rendered width and height at every step. If a word causes a line to overflow <code>size.width</code>, a newline character (<code>'\n'</code>) is generated. If a newline causes the text to overflow <code>size.height</code>, the string is cut off.</p>

<p>The returned string is a (possibly truncated) copy of <code>text</code> with newline characters at appropriate locations.</p>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100 })
// 'lorem ipsum\ndolor sit amet\nconsectetur\nadipiscing elit'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 })
// 'lorem ipsum\ndolor sit amet'</code></pre>

<p>The <code>attrs</code> parameter is an object with SVG attributes that should be set on the temporary SVG text element while it is being measured (such as <code>'font-weight'</code>, <code>'font-size'</code>, <code>'font-family'</code>, etc.). For example, an area of fixed size can obviously fit more words of font size <code>12px</code> than it can fit words of font size <code>36px</code>. If nothing can fit, an empty string is returned. (If an <code>attrs</code> object is not provided, the browser's default style is used.)</p>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 12 })
// 'lorem ipsum dolor\nsit amet consectetur\nadipiscing elit'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 16 })
// 'lorem ipsum\ndolor sit amet'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 36 })
// 'lorem'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 72 })
// ''</code></pre>

<p>The method also accepts the following additional options:</p>

<ul>
    <li><code>opt.separator</code> - a string or a regular expression which denotes how to split the text into words. Defaults to <code>' '</code></li>
    <li><code>opt.eol</code> - a string representing the end-of-line symbol. Defaults to <code>'\n'</code>.</li>
    <li><code>opt.ellipsis</code> - a boolean that specifies whether the ellipsis symbol (<code>'…'</code>, <code>U+2026 HORIZONTAL ELLIPSIS</code>) should be displayed when the text overflows. Defaults to <code>false</code>. If you provide a string, that string will be used as the ellipsis symbol instead.</li>
    <li><code>opt.svgDocument</code> - an SVG document to which the temporary SVG text element should be added. By default, an SVG document is created automatically for you.</li>
    <li><code>opt.hyphen</code> - a string or regex representing the hyphen symbol. If required, the method tries to break long words at hyphens first.</li>
    <li><code>opt.maxLineCount</code> - a number to limit the maximum number of lines.</li>
</ul>

<p>Examples of text with the <code>ellipsis</code> option specified:</p>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 12 }, { ellipsis: true })
// 'lorem ipsum dolor\nsit amet consectetur\nadipiscing elit'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 16 }, { ellipsis: true })
// 'lorem ipsum\ndolor sit ame…'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 16 }, { ellipsis: '...!?' })
// 'lorem ipsum\ndolor sit a...!?'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 36 }, { ellipsis: true })
// 'lore…'</code></pre>

<pre><code>joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 36 }, { ellipsis: true })
// ''</code></pre>

<p>If you need to wrap text inside a <code>text</code> <a href="#dia.attributes.text">attribute</a> of an Element, you should use the <code>textWrap</code> <a href="#dia.attributes.textWrap">attribute</a> instead. It does not require you to provide explicit size measurements, and it automatically responds to element resizing.</p>