util.breakText(text, size [, attrs, opt])
Break the provided text
into lines so that it can fit into the bounding box defined by size.width
and (optionally) size.height
.
The function creates a temporary SVG <text>
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 size.width
, a newline character ('\n'
) is generated. If a newline causes the text to overflow size.height
, the string is cut off.
The returned string is a (possibly truncated) copy of text
with newline characters at appropriate locations.
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100 })
// 'lorem ipsum\ndolor sit amet\nconsectetur\nadipiscing elit'
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 })
// 'lorem ipsum\ndolor sit amet'
The attrs
parameter is an object with SVG attributes that should be set on the temporary SVG text element while it is being measured (such as 'font-weight'
, 'font-size'
, 'font-family'
, etc.). For example, an area of fixed size can obviously fit more words of font size 12px
than it can fit words of font size 36px
. If nothing can fit, an empty string is returned. (If an attrs
object is not provided, the browser's default style is used.)
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'
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 16 })
// 'lorem ipsum\ndolor sit amet'
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 36 })
// 'lorem'
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 72 })
// ''
The method also accepts the following additional options:
opt.separator
- a string or a regular expression which denotes how to split the text into words. Defaults to ' '
opt.eol
- a string representing the end-of-line symbol. Defaults to '\n'
.opt.ellipsis
- a boolean that specifies whether the ellipsis symbol ('…'
, U+2026 HORIZONTAL ELLIPSIS
) should be displayed when the text overflows. Defaults to false
. If you provide a string, that string will be used as the ellipsis symbol instead.opt.svgDocument
- an SVG document to which the temporary SVG text element should be added. By default, an SVG document is created automatically for you.opt.hyphen
- a string or regex representing the hyphen symbol. If required, the method tries to break long words at hyphens first.opt.maxLineCount
- a number to limit the maximum number of lines.Examples of text with the ellipsis
option specified:
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'
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…'
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 16 }, { ellipsis: '...!?' })
// 'lorem ipsum\ndolor sit a...!?'
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 36 }, { ellipsis: true })
// 'lore…'
joint.util.breakText('lorem ipsum dolor sit amet consectetur adipiscing elit', { width: 100, height: 50 }, { 'font-size': 36 }, { ellipsis: true })
// ''
If you need to wrap text inside a text
attribute of an Element, you should use the textWrap
attribute instead. It does not require you to provide explicit size measurements, and it automatically responds to element resizing.