MATLAB Function Reference    

Create text object in current axes



text is the low-level function for creating text graphics objects. Use text to place character strings at specified locations.

text(x,y,'string') adds the string in quotes to the location specified by the point (x,y).

text(x,y,z,'string') adds the string in 3-D coordinates.

text(x,y,z,'string','PropertyName',PropertyValue....) adds the string in quotes to location defined by the coordinates and uses the values for the specified text properties. See the text property list section at the end of this page for a list of text properties.

text('PropertyName',PropertyValue....) omits the coordinates entirely and specifies all properties using property name/property value pairs.

h = text(..) returns a column vector of handles to text objects, one handle per object. All forms of the text function optionally return this output argument.

See the String property for a list of symbols, including Greek letters.


Specify the text location coordinates (the x, y, and z arguments) in the data units of the current axes (see "Examples"). The Extent, VerticalAlignment, and HorizontalAlignment properties control the positioning of the character string with regard to the text location point.

If the coordinates are vectors, text writes the string at all locations defined by the list of points. If the character string is an array the same length as x, y, and z, text writes the corresponding row of the string array at each point specified.

When specifying strings for multiple text objects, the string can be

Each element of the specified string array creates a different text object.

When specifying the string for a single text object, cell arrays of strings and padded string matrices result in a text object with a multiline string, while vertical slash characters are not interpreted as separators and result in a single line string containing vertical slashes.

text is a low-level function that accepts property name/property value pairs as input arguments, however; the convenience form,

is equivalent to:

You can specify other properties only as property name/property value pairs. See the text property list at the end of this page for a description of each property. You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see the set and get reference pages for examples of how to specify these data types).

text does not respect the setting of the figure or axes NextPlot property. This allows you to add text objects to an existing axes without setting hold to on.


The statements,

annotate the point at (pi,0) with the string sin().

The statement,

uses embedded TeX sequences to produce:

See Also

gtext, int2str, num2str, title, xlabel, ylabel, zlabel

The "Labeling Graphs" topic in the online Using MATLAB Graphics manual discusses positioning text.

Object Hierarchy

Setting Default Properties

You can set default text properties on the axes, figure, and root levels.

Where Property is the name of the text property and PropertyValue is the value you are specifying. Use set and get to access text properties.

Property List

The following table lists all text properties and provides a brief description of each. The property name links take you to an expanded description of the properties.

Property Name
Property Description
Property Value
Defining the character string
Enable or disable editing mode.
Values: on, off
Default: off
Enable or disable TeX interpretation
Values: tex, none
Default: tex
The character string (including list of TeX character sequences)
Value: character string
Positioning the character string
Position and size of text object
Values: [left, bottom, width, height]
Horizontal alignment of text string
Values: left, center, right
Default: left
Position of text Extent rectangle
Values: [x, y, z] coordinates
Default: [] empty matrix
Orientation of text object
Values: scalar (degrees)
Default: 0
Units for Extent and Position properties
Values: pixels, normalized, inches, centimeters, points, data
Default: data
Vertical alignment of text string
Values: top, cap, middle, baseline, bottom
Default: middle
Text Bounding Box

Color of text extent rectangle
Values: ColorSpec
Default: none
Color of edge drawn around text extent rectangle
Values: ColorSpec
Default: none
Width of the line (in points) use to draw the box drawn around text extent rectangle
Values: scalar (points)
Default: 0.5
Style of the line use to draw the box drawn around text extent rectangle
Values: -, --, :, -., none
Default: -
Distance in pixels from the text extent to the edge of the box enclosing the text.
Values: scalar (pixels)
Default: 2
Specifying the Font
Select italic-style font
Values: normal, italic, oblique
Default: normal
Select font family
Values: a font supported by your system or the string FixedWidth
Default: Helvetica
Size of font
Values: size in FontUnits
Default: 10 points
Units for FontSize property
Values: points, normalized, inches, centimeters, pixels
Default: points
Weight of text characters
Values: light, normal, demi, bold
Default: normal
Controlling the Appearance
Clipping to axes rectangle
Values: on, off
Default: on
Method of drawing and erasing the text (useful for animation)
Values: normal, none, xor, background
Default: normal
Highlight text when selected (Selected property set to on)
Values: on, off
Default: on
Make the text visible or invisible
Values: on, off
Default: on
Color of the text
Controlling Access to Text Objects
Determines if and when the the text's handle is visible to other functions
Values: on, callback, off
Default: on
Determines if the text can become the current object (see the figure CurrentObject property)
Values: on, off
Default: on
General Information About Text Objects
Text objects have no children
Values: [] (empty matrix)
The parent of a text object is always an axes object
Value: axes handle
Indicate whether the text is in a "selected" state.
Values: on, off
Default: off
User-specified label
Value: any string
Default: '' (empty string)
The type of graphics object (read only)
Value: the string 'text'
User-specified data
Values: any matrix
Default: [] (empty matrix)
Controlling Callback Routine Execution
Specifies how to handle callback routine interruption
Values: cancel, queue
Default: queue
Defines a callback routine that executes when a mouse button is pressed on over the text
Values: string or function handle
Default: '' (empty string)
Defines a callback routine that executes when an text is created
Values: string or function handle
Default: '' (empty string)
Defines a callback routine that executes when the text is deleted (via close or delete)
Values: string or function handle
Default: '' (empty string)
Determines if callback routine can be interrupted
Values: on, off
Default: on (can be interrupted)
Associates a context menu with the text
Values: handle of a uicontextmenu

  texlabel Text Properties