13 Text

13.1 Introduction

SVG allows text to be inserted into the drawing. All of the same styling attributes available for paths and vector graphic shapes are also available for text. (See Filling, Stroking and Paint Servers.)

13.2 The <text> element

The <text> element adds text to a drawing.

SVG requires that all SVG text data be specified within a <text> element. This allows the SVG processor to know unambiguously how to render the text. Furthermore, it provides enough information to the SVG processor to allow it to stitch together separately drawn strings of text into textflows. (See Defining Text Flows: the <textflow> element.)

You have two choices for how to specify the text strings to be drawn:

  1. As standard XML character data between <text> and </text>
  2. By providing a <src href="..." /> subelement to a <text> element. (The <src> element is defined as an XLink. Note that the XLink specification is currently under development and is subject to change. The SVG working group will track and rationalize with XLink as it evolves.) The text string to be used is the character data within the element(s) referenced by the <uri> value given as the value of href.

In the example below, the first <text> element (with id="TextToUse") will not draw because it is part of a <defs> element. The second <text> element draws the string "ABC". The third text element draws the string "XYZ" because it includes a <src> element which is a reference to element "TextToUse", and that element's character data is "XYZ":

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG April 1999//EN" 
<svg width="4in" height="3in">
    <text id="TextToUse">XYZ</text>
    <src href="#TextToUse"/>

Download this example

<text> elements which are not positioned along a path (see Text On A Path below) can supply optional attributes x= and y= which represents the location in user coordinates (or Transformed CSS units or a percentage of the current viewport) for the initial current text position. (Default values for x= and y= are the previous current text position from the end of the previous <text> element within the same <textflow> or, if there is no such previous <text> element, zero in the user coordinate system .) For left-aligned character strings, the placement point of the first glyph will be positioned exactly at the current text position and the glyph will be rendered based on the current set of text and font properties. After the glyph is rendered, the current text position is advanced based on the metrics of the glyph that were used along with the current set of text and font properties. For Roman text, the current text position is advanced along the x-axis by the width of that glyph. The cycle repeats until all characters in the <text> element have been rendered.

(Internationalization issues need to be addressed.)

13.3 Defining Text Flows: the <textflow> element

SVG provides a <textflow> element to allow generators of SVG to specify text selection order, even when the contents of a text flow are distributed throughout the canvas. When feasible, generators of SVG should attempt to use this facility to order their text strings to facilitate properly ordered text selection within SVG viewing applications such as Web browsers.

The <textflow> element defines the selection order for multiple <text> elements within a given SVG document.

A simple (and very common) case is when the selection order for text exactly matches the order in which the text is position within an SVG file. This case is handled simply:

<?xml version="1.0" standalone="yes"?>
<svg width="4in" height="3in"
 xmlns = 'http://www.w3.org/Graphics/SVG/svg-19990412.dtd'>
  <textflow id="TF1">
    <text x="100" y="100">123</text>

Download this example

A <textflow> element can contain any combination of <t> child elements (which are references to <text> elements defined elsewhere) or direct inclusion of <text> elements.

When multiple <text> elements are included as part of a given <textflow> element, then the final current position of the given <text> element is the initial default current position for the next <text> element. (Note: for the first <text> element within a <textflow> element or for a <text> element that is not associated with a <textflow>, the initial default current position is (0,0) in the current user coordinate system.

Within an SVG viewing application which supports text selection, the following behavior should exist. When the mouse is clicked over an SVG character and then the mouse is dragged, whenever the mouse goes over another character within the same <textflow>, all characters whose selection order is between the initial character and the current character should be highlighted, no matter where they might be located on the canvas.

(??? Insert drawing here)

13.4 Text and Font Properties

(Descriptions (or references to the CSS2 spec) for all of the text and font properties from CSS2 go here. The following are SVG-specific text properties which go beyond the text and font properties already defined in CSS2:)

Value:   true | false | inherit
Initial:   false
Applies to:  <text> elements
Inherited:  yes
Percentages:  N/A
Media:  visual

'text-antialiasing' indicates whether text strings should be drawn with antialiased rendering. This property is a hint to the user agent which is expected to be honored in commercial SVG processors.

Text strings should be drawn with antialiased rendering.
Text strings should be drawn without antialiasing.

13.5 Ligatures and Alternate Glyphs

There are situations such as ligatures, special-purpose fonts (e.g., a font for music symbols) or alternate glyphs for Asian text strings where a different glyph should be used to render some text than the glyph which normally corresponds to the given character data. Also, the W3C Character Model (??? add link) requires early normalization of character data to facilitate meaningful and unambiguous exchange of character data and correct comparisons between character strings. The W3C Character Model will bring about many common situations where the normalized character data will be different than the glyphs which the user want to use to render that character data.

To allow for control over the glyphs used to render particular character data, the 'altglyph' property is available.

Value:   unicode(<value>) |
glyphname(<string>) |
glyphid(<value>) |
ROS(<value>) cid(<value>) |
Initial:   none
Applies to:  <text> elements
Inherited:  yes
Percentages:  N/A
Media:  visual
where <value> indicates a string of Unicode characters that should replace the text within the <text> element
where <string> provides a string of which is the name of the glyph that should be used to replace the text within the <text> element
where <value> a string of which is numeric ID/index of the glyph that should be used to replace the text within the <text> or <t> element
ROS and cid
are required for Web fonts in OpenType/CFF format and operate similar to glyphid

13.6 Text on a path

In addition to text drawn in a straight line, SVG also includes the ability to place text along the shape of a <path> element. The basic algorithm is such that each glyph is positioned at a specific point on the path, with the glyph getting rotated such that the baseline of the glyph is either parallel or tangent to the tangent of the curve at the given point. Here are some examples of text on a path:

(??? include some drawings here )

The following is a simple example which illustrates many of the basic concepts:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG April 1999//EN" 
<svg width="4in" height="3in">
  <desc>Simple text on a path
  <path id="MyPath" style="visibility: hidden"
        d="M 100 100 C 125 125 175 125 200 100" />
  <text><textpath href="#MyPath"/>Text on path</text>

Download this example

The start-offset attribute defines the distance from the start of the path where the first character should be positioned.

Various CSS properties control aspects of text drawn along a path. The standard set of text and font properties from CSS2 apply, including 'text-align' and 'vertical-align'. Additional, the following additional properties control how the text is formatted and rendered:

Text on a path opens the possibility of significant implementation differences due to different methods of calculating distance along a path. In order to ensure that distance calculations are sufficiently precise, the following two attributes are available on <path> elements. (??? Obviously, this section needs to be moved to the <path> element section.)

(??? Insert drawings here)

13.6.1 Vector graphics along a path

SVG's text on a path features set has been generalized to allow for arbitrary SVG along a path, by adding the use element as a valid child of text.