Text

returns SVG.Text which inherits from SVG.Shape

Unlike html, text in svg is much harder to tame. There is no way to create flowing text, so newlines should be entered manually. In SVG.js there are two ways to create text elements.

The first and easiest method is to provide a string of text, split by newlines:

var text = draw.text("Lorem ipsum dolor sit amet consectetur.\nCras sodales imperdiet auctor.")

This will automatically create a block of text and insert newlines where necessary.

The second method will give you much more control but requires a bit more code:

var text = draw.text(function(add) {
  add.tspan('Lorem ipsum dolor sit amet ').newLine()
  add.tspan('consectetur').fill('#f06')
  add.tspan('.')
  add.tspan('Cras sodales imperdiet auctor.').newLine().dx(20)
  add.tspan('Nunc ultrices lectus at erat').newLine()
  add.tspan('dictum pharetra elementum ante').newLine()
})

If you want to go the other way and don't want to add tspans at all, just one line of text, you can use the plain() method instead:

var text = draw.plain('Lorem ipsum dolor sit amet consectetur.')

This is a shortcut to the plain method on the SVG.Text instance which doesn't render newlines at all.

build()

returns itself

The build() can be used to enable / disable build mode. With build mode disabled, the plain() and tspan() methods will first call the clear() bethod before adding the new content. So when build mode is enabled, plain() and tspan() will append the new content to the existing content. When passing a block to the text() method, build mode is toggled automatically before and after the block is called. But in some cases it might be useful to be able to toggle it manually:

var text = draw.text('This is just the start, ')

text.build(true)  // enables build mode

var tspan = text.tspan('something pink in the middle ').fill('#00ff97')
text.plain('and again boring at the end.')

text.build(false) // disables build mode

tspan.animate('2s').fill('#f06')

clear()

returns itself

Clear all the contents of the called text element:

text.clear()

length()

returns number

Gets the total computed text length of all tspans together:

text.length()

font()

returns itself

A convenience method to add font-related properties:

text.font({
  family:   'Helvetica'
, size:     144
, anchor:   'middle'
, leading:  '1.5em'
})

Available properties are:

  • leading (will do the same as calling the leading() method as setter)
  • anchor (will set the text-anchor attribute)
  • family (will set the font-family attribute)
  • size (will set the font-size attribute)
  • stretch (will set the font-stretch attribute)
  • style (will set the font-style attribute)
  • variant (will set the font-variant attribute)
  • weight (will set the font-weight attribute)

Any other property will be applied as given. So for example the letter-spacing property will just be applied as it would be given to the attr() method. More on font-related properties here.

leading() as setter

returns itself
animate yes

As opposed to html, where leading is defined by line-height, svg does not have a natural leading equivalent. In svg, lines are not defined naturally. They are defined by <tspan> nodes with a dy attribute defining the line height and an x value resetting the line to the x position of the parent text element. But you can also have many nodes in one line defining a different y, dy, x or even dx value. This gives us a lot of freedom, but also a lot more responsibility. We have to decide when a new line is defined, where it starts, what its offset is and what it's height is. The leading() method in SVG.js tries to ease the pain by giving you behaviour that is much closer to html. In combination with newline separated text, it works just like html:

var text = draw.text("Lorem ipsum dolor sit amet consectetur.\nCras sodales imperdiet auctor.")
text.leading(1.3)

This will render a text element with a tspan element for each line, with a dy value of 130% of the font size.

Note that the leading() method assumes that every first level tspan in a text node represents a new line. Using leading() on text elements containing multiple tspans in one line (e.g. without a wrapping tspan defining a new line) will render scrambled. So it is advisable to use this method with care, preferably only when throwing newline separated text at the text element or calling the newLine() method on every first level tspan added in the block passed as an argument to the text element.

leading() as getter

returns value

Get the current leading value:

var leading = text.leading()

lines()

returns SVG.Set

All first level tspans can be referenced with the lines() method:

text.lines()

This will return an instance of SVG.Set including all tspan elements.

plain()

returns itself

If the content of the element doesn't need any styling or multiple lines, it might be sufficient to just add some plain text:

text.plain('I do not have any expectations.')

rebuild()

returns itself

This is an internal callback that probably never needs to be called manually. Basically it rebuilds the text element whenerver font-size and x attributes or the leading() of the text element are modified. This method also acts a setter to enable or disable rebuilding:

text.rebuild(false) //-> disables rebuilding
text.rebuild(true)  //-> enables rebuilding and instantaneously rebuilds the text element

text() as setter

returns itself

Changing text afterwards is also possible with the text() method:

text.text('Brilliant!')

text() as getter

returns string

To get the raw text content:

text.text()

tspan()

returns SVG.Tspan

Just adding one tspan is also possible:

text.tspan(' on a train...').fill('#f06')


TextPath

returns SVG.TextPath which inherits from SVG.Text

A nice feature in svg is the ability to run text along a path:

var text = draw.text(function(add) {
  add.tspan('We go ')
  add.tspan('up').fill('#f09').dy(-40)
  add.tspan(', then we go down, then up again').dy(40)
})

var path = 'M 100 200 C 200 100 300 0 400 100 C 500 200 600 300 700 200 C 800 100 900 100 900 100'

text.path(path).font({ size: 42.5, family: 'Verdana' })

When calling the path() method on a text element, the text element is mutated into an intermediate between a text and a path element. From that point on the text element will also feature a plot() method to update the path:

text.plot('M 300 500 C 200 100 300 0 400 100 C 500 200 600 300 700 200 C 800 100 900 100 900 100')

Attributes specific to the <textPath> element can be applied to the textPath instance itself:

text.textPath().attr('startOffset', '50%')

And they can be animated as well of course:

text.textPath().animate(3000).attr('startOffset', '80%')

Note: If a startOffset other than a percentage is given, then the value represents a distance along the path measured in the current user coordinate system.

array()

returns SVG.PathArray

Get the path array of the underlying path:

var array = text.textPath().array()

plot()

returns itself
animate yes

Change the path on the textpath element:

text.textPath().plot('M 300 500 C 200 100 300 0 400 100 C 500 200 600 300 700 200')

textPath()

returns SVG.TextPath

Referencing the textPath node directly:

var textPath = text.textPath()

track()

returns SVG.Path

Referencing the linked path element directly:

var path = text.track()



Note: SVG.TextPath inherits from SVG.Text, so all those methods are inherited as well.

Events

The text element has one event. It is fired every time the rebuild() method is called:

text.on('rebuild', function() {
  // whatever you need to do after rebuilding
})
Fork me on GitHub