12 Text


Contents


 

12.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.)

12.2 The <text> element

The <text> element adds text to a drawing.

In the example below, the string "Hello, out there" is drawn in blue:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <text x=".5in" y="2in" 
        style="fill:blue">Hello, out there</text>
</svg>

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 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.

Within a <text> element, text and font properties and the current text position can be modified by including a <tspan> element. The <tspan> element can contain attributes style (which allows new visual rendering attributes to be specified) and the following attributes, which perform adjustments on the current text position:

The x and dx values are cumulative; thus, if both are provided, the new current text position will have an X-coordinate of x+dx (i.e., after dx is converted into the user coordinate system). Similarly, if both y and dy are provided, the new current text position will have a Y-coordinate of y+dy (i.e., after dy is converted into the user coordinate system).

(Internationalization issues need to be addressed.)

A <tspan> element can also be used to specify that the character data from a different element should be used as character data for the given <tspan> element. 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 <tspan> 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 August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <defs>
    <text id="TextToUse">XYZ</text>
  </defs>
  <text>ABC</text>
  <text>
    <tspan xlink:href="#TextToUse"/>
  </text>
</svg>

Download this example

If a <tspan> element has both an href attribute and its own character data, the character data from the href attribute draws before its own character data.

12.3 White space handling

SVG supports the standard XML attribute xml:space for determining how it should handle white space characters within a given <text> element's character data. xml:space is an inheritable attribute which can have one of two values:

12.4 Text selection

SVG user agents running on systems with have clipboards for copy/paste operations and which are equipped with input devices that allow for text selection should support the selection of text from an SVG document and the ability to copy selected text strings to the system clipboard.

Within an SVG user agent which supports text selection and pointer devices such as a mouse, the following behavior should exist. When the pointing device is clicked over an SVG character and then dragged, then whenever the mouse goes over another character defined within the same <text> elements, all characters whose position in the document is between the initial character and the current character should be highlighted, no matter where they might be located on the canvas.

When feasible, generators of SVG should attempt to order their text strings to facilitate properly ordered text selection within SVG viewing applications such as Web browsers.

12.5 Text and font properties

12.5.1 Introduction

SVG uses CSS properties to describe many of its font and text properties.

12.5.2 CSS font properties used by SVG

SVG uses the following font specification properties from CSS2. The detailed description of these properties can be found in the "Cascading Style Sheets (CSS) level 2" specification [CSS2]: Any SVG-specific notes about these properties are contained in the descriptions below.

'font-family'
Value:  [[ <family-name> |
<generic-family> ],]* [<family-name> |
<generic-family>] | inherit
Initial:  depends on user agent
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property which font family is to be used to render the text, specified as a prioritized list of font family names and/or generic family names. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'font-style'
Value:  normal | italic | oblique | inherit
Initial:  normal
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property specifies whether the text is to be rendered using a normal, italic or oblique face. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'font-variant'
Value:  normal | small-caps | inherit
Initial:  normal
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property indicates whether the text is to be rendered using the normal glyphs for lowercase characters or using small-caps glyphs for lowercase characters. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'font-weight'
Value:  normal | bold | bolder | lighter | 100 | 200 | 300
| 400 | 500 | 600 | 700 | 800 | 900 | inherit
Initial:  normal
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property refers to the boldness or lightness of the glyphs used to render the text, relative to other fonts in the same font family. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'font-stretch'
Value:  normal | wider | narrower |
ultra-condensed | extra-condensed |
condensed | semi-condensed |
semi-expanded | expanded |
extra-expanded | ultra-expanded | inherit
Initial:  normal
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property indicates the desired amount of condensing or expansion in the glyphs used to render the text. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'font-size'
Value:  <absolute-size> | <relative-size> |
<length> | <percentage> | inherit
Initial:  medium
Applies to:  all elements
Inherited:  yes, the computed value is inherited
Percentages:  refer to parent element's font size
Media:  visual

This property refers to the size of the font from baseline to baseline, when set solid (in CSS terms, this is when the 'font-size' and 'line-height' properties have the same value). Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'font-size-adjust'
Value:  <number> | none | inherit
Initial:  none
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property allows authors to specify an aspect value for an element that will preserve the x-height of the first choice font in a substitute font. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'font'
Value:  [ [ <'font-style'> || <'font-variant'> || <'font-weight'> ]?
<'font-size'> [ / <'line-height'> ]? <'font-family'> ] |
caption | icon | menu | message-box|
small-caption | status-bar | inherit
Initial:  see individual properties
Applies to:  all elements
Inherited:  yes
Percentages:  allowed on 'font-size' and 'line-height'
Media:  visual

Shorthand property for setting 'font-style', 'font-variant', 'font-weight', 'font-size', 'line-height' and 'font-family'. The 'line-height' property setting will be ignored by the SVG user agent. Conforming SVG Viewers are not required to support the various system font options (caption, icon, menu, message-box, small-caption and status-bar) and can use a system font or one of the generic fonts instead.

Note that SVG allows unit-less values in CSS properties (see Units). This causes a potential ambiguity with property settings such as 'font:100 serif' in deciding whether the number represents a 'font-weight' or a 'font-size'. To resolve this ambiguity, font-size specifications in user units within a 'font' shorthand property are required to have the suffix "uu" (e.g., 'font:100uu serif').

Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

12.5.3 CSS text properties used by SVG

'text-align'
Value:  left | right | center | justify | <string> | inherit
Initial:  depends on user agent and writing direction
Applies to:  block-level elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property describes how the characters within a <text> element should be aligned relative to the initial position for the <text> element. Values have the following meanings:

left, right, and center
Left-align, right-align and center the text, respectively, relative to the initial position for the <text> element. For left, position the first glyph at the initial position. For right and center, before painting the text, determine what the final offset would be if the text were painted with 'text-align:left' and compute the necessary adjustment of the initial position to achieve right- or center- alignment.
justify and <string>
These options from CSS2 [CSS2] are not supported by SVG. Specifying them will result in a value of left being used.
'vertical-align'
Value:  baseline | sub | super | top | text-top | middle | bottom | text-bottom | <percentage> | <<length> | inherit
Initial:  baseline
Applies to:  inline-level and 'table-cell' elements
Inherited:  no
Percentages:  refer to the 'line-height' of the element itself
Media:  visual

This property affects the vertical positioning of glyphs within a <text> elements. Using the CSS2 model for fonts as described in the "Cascading Style Sheets (CSS) level 2" specification [CSS2], each font has various characteristics that are either implicit in the font itself or provided explicitly via a CSS2 font descriptor. These characteristics include the following vertical position points: a baseline, an x-height, a top, a bottom and, therefore, a middle. The 'vertical-align' property indicates how individual glyphs should be aligned vertically with respect to the vertical position points in the relevant font.

baseline
Align the baseline of the glyph with the baseline of the font.
middle
Align the vertical midpoint of the glyph with the baseline of the parent box plus half the x-height of the font.
sub
Lower the baseline of the glyph to the proper position for a subscript for the font.
super
Raise the baseline of the glyph to the proper position for a superscript for the font.
text-top
Align the top of the glyph with the top of the font.
text-bottom
Align the bottom of the glyph with the bottom of the font.
<percentage>
Raise (positive value) or lower (negative value) the glyph by this distance (a percentage of the 'font-size' value). The value '0%' means the same as 'baseline'.
<length>
Raise (positive value) or lower (negative value) the glyph by this distance. The value '0cm' means the same as 'baseline'.
top
Same as text-top.
bottom
Same as text-bottom.
'text-decoration'
Value:  none | [ underline || overline || line-through || blink ] | inherit
Initial:  none
Applies to:  all elements
Inherited:  no (see prose)
Percentages:  N/A
Media:  visual

This property describes decorations that are added to the text of an element. Conforming SVG Viewers are not required to support the blink value. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'letter-spacing'
Value:  normal | <length> | inherit
Initial:  normal
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property specifies spacing behavior between text characters. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'word-spacing'
Value:  normal | <length> | inherit
Initial:  normal
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property specifies spacing behavior between words. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'text-advance'
Value:  horizontal | vertical | vertical-ideographic | inherit
Initial:  horizontal
Applies to:  all elements
Inherited:  yes
Percentages:  N/A
Media:  visual

This property specifies whether text strings should be drawn as horizontal or vertical text. (More detailed descriptions will come later.)

'direction'
Value:  ltr | rtl | inherit
Initial:  ltr
Applies to:  all elements, but see prose
Inherited:  yes
Percentages:  N/A
Media:  visual

This property specifies the base writing direction of text. Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

'unicode-bidi'
Value:  normal | embed | bidi-override | inherit
Initial:  normal
Applies to:  all elements, but see prose
Inherited:  no
Percentages:  N/A
Media:  visual

Refer to the "Cascading Style Sheets (CSS) level 2" specification [CSS2] for more information.

12.6 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.

'altglyph'
Value:   unicode(<value>) |
glyphname(<string>) |
glyphid(<value>) |
ROS(<value>) cid(<value>) |
inherit
Initial:   none
Applies to:  <text> elements
Inherited:  yes
Percentages:  N/A
Media:  visual
unicode(<value>))
where <value> indicates a string of Unicode characters that should replace the text within the <text> element
glyphname(<string>))
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
glyphid(<value>))
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

12.7 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 August 1999//EN" 
  "http://www.w3.org/Graphics/SVG/SVG-19990812.dtd">
<svg width="4in" height="3in">
  <desc>Simple text on a path
  </desc>
  <defs>
    <path id="MyPath"
          d="M 100 100 C 125 125 175 125 200 100" />
  </defs>
  <text>
    <textPath xlink:href="#MyPath">Text on path</textPath>
  </text>
</svg>

Download this example

The startOffset 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)

12.7.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.