### Navigation

- index
- modules |
- next |
- previous |
- home|
- examples|
- tutorials|
- pyplot|
- docs »
- The Matplotlib API »

# text

## `matplotlib.text`

Classes for including text in a figure.

class `matplotlib.text.``Annotation`(s, xy, xytext=None, xycoords=’data’, textcoords=None, arrowprops=None, annotation_clip=None, **kwargs)

  Bases: `matplotlib.text.Text`, `matplotlib.text._AnnotationBase`

  Annotate the point `xy` with text `s`.

  Additional kwargs are passed to `Text`.

  > Parameters: | s : str The text of the annotation xy : iterable Length 2 sequence specifying the (x,y) point to annotate xytext : iterable, optional Length 2 sequence specifying the (x,y) to place the text at. If None, defaults to `xy`. xycoords : str, Artist, Transform, callable or tuple, optional The coordinate system that `xy` is given in. For a `str` the allowed values are:
  > Property | Description
  > --- | ---
  > ‘figure points’ | points from the lower left of the figure
  > ‘figure pixels’ | pixels from the lower left of the figure
  > ‘figure fraction’ | fraction of figure from lower left
  > ‘axes points’ | points from lower left corner of axes
  > ‘axes pixels’ | pixels from lower left corner of axes
  > ‘axes fraction’ | fraction of axes from lower left
  > ‘data’ | use the coordinate system of the object being annotated (default)
  > ‘polar’ | (theta,r) if not native ‘data’ coordinates
  > If a `Artist` object is passed in the units are fraction if it’s bounding box. If a `Transform` object is passed in use that to transform `xy` to screen coordinates If a callable it must take a `RendererBase` object as input and return a `Transform` or `Bbox` object If a `tuple` must be length 2 tuple of str, `Artist`, `Transform` or callable objects. The first transform is used for the x coordinate and the second for y. See Advanced Annotation for more details. Defaults to `'data'` textcoords : str, `Artist`, `Transform`, callable or tuple, optional The coordinate system that `xytext` is given, which may be different than the coordinate system used for `xy`. All `xycoords` values are valid as well as the following strings:
  > Property | Description
  > --- | ---
  > ‘offset points’ | offset (in points) from the xy value
  > ‘offset pixels’ | offset (in pixels) from the xy value
  > defaults to the input of `xycoords` arrowprops : dict, optional If not None, properties used to draw a `FancyArrowPatch` arrow between `xy` and `xytext`. If `arrowprops` does not contain the key `'arrowstyle'` the allowed keys are:
  > Key | Description
  > --- | ---
  > width | the width of the arrow in points
  > headwidth | the width of the base of the arrow head in points
  > headlength | the length of the arrow head in points
  > shrink | fraction of total length to ‘shrink’ from both ends
  > ? | any key to `matplotlib.patches.FancyArrowPatch`
  > If the `arrowprops` contains the key `'arrowstyle'` the above keys are forbidden. The allowed values of `'arrowstyle'` are:
  > Name | Attrs
  > --- | ---
  > `'-'` | None
  > `'->'` | head_length=0.4,head_width=0.2
  > `'-['` | widthB=1.0,lengthB=0.2,angleB=None
  > `'|-|'` | widthA=1.0,widthB=1.0
  > `'-|>'` | head_length=0.4,head_width=0.2
  > `'<-'` | head_length=0.4,head_width=0.2
  > `'<->'` | head_length=0.4,head_width=0.2
  > `'<|-'` | head_length=0.4,head_width=0.2
  > `'<|-|>'` | head_length=0.4,head_width=0.2
  > `'fancy'` | head_length=0.4,head_width=0.4,tail_width=0.4
  > `'simple'` | head_length=0.5,head_width=0.5,tail_width=0.2
  > `'wedge'` | tail_width=0.3,shrink_factor=0.5
  > Valid keys for `FancyArrowPatch` are:
  > Key | Description
  > --- | ---
  > arrowstyle | the arrow style
  > connectionstyle | the connection style
  > relpos | default is (0.5, 0.5)
  > patchA | default is bounding box of the text
  > patchB | default is None
  > shrinkA | default is 2 points
  > shrinkB | default is 2 points
  > mutation_scale | default is text size (in points)
  > mutation_aspect | default is 1.
  > ? | any key for `matplotlib.patches.PathPatch`
  Defaults to None annotation_clip : bool, optional Controls the visibility of the annotation when it goes outside the axes area. If `True`, the annotation will only be drawn when the `xy` is inside the axes. If `False`, the annotation will always be drawn regardless of its position. The default is `None`, which behave as `True` only if xycoords is “data”.
  Returns: | Annotation

  `anncoords`
  `contains`(event)
  `draw`(renderer)

    Draw the `Annotation` object to the given renderer.

  `get_window_extent`(renderer=None)

    Return a `Bbox` object bounding the text and arrow annotation, in display units.

    renderer defaults to the _renderer attribute of the text object. This is not assigned until the first execution of `draw()`, so you must use this kwarg if you want to call `get_window_extent()` prior to the first `draw()`. For getting web page regions, it is simpler to call the method after saving the figure. The dpi used defaults to self.figure.dpi; the renderer dpi is irrelevant.

  `set_figure`(fig)
  `update_positions`(renderer)

    “Update the pixel positions of the annotated point and the text.

  `xyann`

class `matplotlib.text.``OffsetFrom`(artist, ref_coord, unit=’points’)

  Bases: `object`

  Callable helper class for working with `Annotation`

  Parameters: | artist : `Artist`, `BboxBase`, or `Transform` The object to compute the offset from. ref_coord : length 2 sequence If `artist` is an `Artist` or `BboxBase`, this values is the location to of the offset origin in fractions of the `artist` bounding box. If `artist` is a transform, the offset origin is the transform applied to this value. unit : {‘points, ‘pixels’} The screen units to use (pixels or points) for the offset input.

  `get_unit`()

    The unit for input to the transform used by `__call__`

  `set_unit`(unit)

    The unit for input to the transform used by `__call__`

    Parameters: | unit : {‘points’, ‘pixels’}

class `matplotlib.text.``Text`(x=0, y=0, text=”, color=None, verticalalignment=’baseline’, horizontalalignment=’left’, multialignment=None, fontproperties=None, rotation=None, linespacing=None, rotation_mode=None, usetex=None, wrap=False, **kwargs)

  Bases: `matplotlib.artist.Artist`

  Handle storing and drawing of text in window or data coordinates.

  Create a `Text` instance at x, y with string text.

  Valid kwargs are

  > Property | Description
  > --- | ---
  > `agg_filter` | unknown
  > `alpha` | float (0.0 transparent through 1.0 opaque)
  > `animated` | [True | False]
  > `axes` | an `Axes` instance
  > `backgroundcolor` | any matplotlib color
  > `bbox` | FancyBboxPatch prop dict
  > `clip_box` | a `matplotlib.transforms.Bbox` instance
  > `clip_on` | [True | False]
  > `clip_path` | [ (`Path`, `Transform`) | `Patch` | None ]
  > `color` | any matplotlib color
  > `contains` | a callable function
  > `family` or fontfamily or fontname or name | [FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ | ‘monospace’ ]
  > `figure` | a `matplotlib.figure.Figure` instance
  > `fontproperties` or font_properties | a `matplotlib.font_manager.FontProperties` instance
  > `gid` | an id string
  > `horizontalalignment` or ha | [ ‘center’ | ‘right’ | ‘left’ ]
  > `label` | string or anything printable with ‘%s’ conversion.
  > `linespacing` | float (multiple of font size)
  > `multialignment` | [‘left’ | ‘right’ | ‘center’ ]
  > `path_effects` | unknown
  > `picker` | [None|float|boolean|callable]
  > `position` | (x,y)
  > `rasterized` | [True | False | None]
  > `rotation` | [ angle in degrees | ‘vertical’ | ‘horizontal’ ]
  > `rotation_mode` | unknown
  > `size` or fontsize | [size in points | ‘xx-small’ | ‘x-small’ | ‘small’ | ‘medium’ | ‘large’ | ‘x-large’ | ‘xx-large’ ]
  > `sketch_params` | unknown
  > `snap` | unknown
  > `stretch` or fontstretch | [a numeric value in range 0-1000 | ‘ultra-condensed’ | ‘extra-condensed’ | ‘condensed’ | ‘semi-condensed’ | ‘normal’ | ‘semi-expanded’ | ‘expanded’ | ‘extra-expanded’ | ‘ultra-expanded’ ]
  > `style` or fontstyle | [ ‘normal’ | ‘italic’ | ‘oblique’]
  > `text` | string or anything printable with ‘%s’ conversion.
  > `transform` | `Transform` instance
  > `url` | a url string
  > `usetex` | unknown
  > `variant` or fontvariant | [ ‘normal’ | ‘small-caps’ ]
  > `verticalalignment` or ma or va | [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ]
  > `visible` | [True | False]
  > `weight` or fontweight | [a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ | ‘normal’ | ‘regular’ | ‘book’ | ‘medium’ | ‘roman’ | ‘semibold’ | ‘demibold’ | ‘demi’ | ‘bold’ | ‘heavy’ | ‘extra bold’ | ‘black’ ]
  > `wrap` | unknown
  > `x` | float
  > `y` | float
  > `zorder` | any number

  `contains`(mouseevent)

    Test whether the mouse event occurred in the patch.

    In the case of text, a hit is true anywhere in the axis-aligned bounding-box containing the text.

    Returns True or False.

  `draw`(renderer)

    Draws the `Text` object to the given renderer.

  `get_bbox_patch`()

    Return the bbox Patch object. Returns None if the FancyBboxPatch is not made.

  `get_color`()

    Return the color of the text

  `get_family`()

    Return the list of font families used for font lookup

  `get_font_properties`()

    alias for get_fontproperties

  `get_fontfamily`()

    alias for get_family

  `get_fontname`()

    alias for get_name

  `get_fontproperties`()

    Return the `FontProperties` object

  `get_fontsize`()

    alias for get_size

  `get_fontstretch`()

    alias for get_stretch

  `get_fontstyle`()

    alias for get_style

  `get_fontvariant`()

    alias for get_variant

  `get_fontweight`()

    alias for get_weight

  `get_ha`()

    alias for get_horizontalalignment

  `get_horizontalalignment`()

    Return the horizontal alignment as string. Will be one of ‘left’, ‘center’ or ‘right’.

  `get_name`()

    Return the font name as string

  `get_position`()

    Return the position of the text as a tuple (x, y)

  `get_prop_tup`(renderer=None)

    Return a hashable tuple of properties.

    Not intended to be human readable, but useful for backends who want to cache derived information about text (e.g., layouts) and need to know if the text has changed.

  `get_rotation`()

    return the text angle as float in degrees

  `get_rotation_mode`()

    get text rotation mode

  `get_size`()

    Return the font size as integer

  `get_stretch`()

    Get the font stretch as a string or number

  `get_style`()

    Return the font style as string

  `get_text`()

    Get the text as string

  `get_unitless_position`()

    Return the unitless position of the text as a tuple (x, y)

  `get_usetex`()

    Return whether this `Text` object will render using TeX.

    If the user has not manually set this value, it will default to the value of `rcParams['text.usetex']`

  `get_va`()

    alias for `getverticalalignment()`

  `get_variant`()

    Return the font variant as a string

  `get_verticalalignment`()

    Return the vertical alignment as string. Will be one of ‘top’, ‘center’, ‘bottom’ or ‘baseline’.

  `get_weight`()

    Get the font weight as string or number

  `get_window_extent`(renderer=None, dpi=None)

    Return a `Bbox` object bounding the text, in display units.

    In addition to being used internally, this is useful for specifying clickable regions in a png file on a web page.

    renderer defaults to the _renderer attribute of the text object. This is not assigned until the first execution of `draw()`, so you must use this kwarg if you want to call `get_window_extent()` prior to the first `draw()`. For getting web page regions, it is simpler to call the method after saving the figure.

    dpi defaults to self.figure.dpi; the renderer dpi is irrelevant. For the web application, if figure.dpi is not the value used when saving the figure, then the value that was used must be specified as the dpi argument.

  `get_wrap`()

    Returns the wrapping state for the text.

  static `is_math_text`(s, usetex=None)

    Returns a cleaned string and a boolean flag. The flag indicates if the given string s contains any mathtext, determined by counting unescaped dollar signs. If no mathtext is present, the cleaned string has its dollar signs unescaped. If usetex is on, the flag always has the value “TeX”.

  `set_backgroundcolor`(color)

    Set the background color of the text by updating the bbox.

    See also

    `set_bbox()`
      To change the position of the bounding box.

    ACCEPTS: any matplotlib color

  `set_bbox`(rectprops)

    Draw a bounding box around self. rectprops are any settable properties for a FancyBboxPatch, e.g., facecolor=’red’, alpha=0.5.

    > t.set_bbox(dict(facecolor=’red’, alpha=0.5))

    The default boxstyle is ‘square’. The mutation scale of the FancyBboxPatch is set to the fontsize.

    ACCEPTS: FancyBboxPatch prop dict

  `set_clip_box`(clipbox)

    Set the artist’s clip `Bbox`.

    ACCEPTS: a `matplotlib.transforms.Bbox` instance

  `set_clip_on`(b)

    Set whether artist uses clipping.

    When False artists will be visible out side of the axes which can lead to unexpected results.

    ACCEPTS: [True | False]

  `set_clip_path`(path, transform=None)

    Set the artist’s clip path, which may be:

    > - a `Patch` (or subclass) instance

    > - a `Path` instance, in which case

    >     an optional `Transform` instance may be provided, which will be applied to the path before using it for clipping.

    > - None, to remove the clipping path

    For efficiency, if the path happens to be an axis-aligned rectangle, this method will set the clipping box to the corresponding rectangle and set the clipping path to None.

    ACCEPTS: [ (`Path`, `Transform`) | `Patch` | None ]

  `set_color`(color)

    Set the foreground color of the text

    ACCEPTS: any matplotlib color

  `set_family`(fontname)

    Set the font family. May be either a single string, or a list of strings in decreasing priority. Each string may be either a real font name or a generic font class name. If the latter, the specific font names will be looked up in the `matplotlibrc` file.

    ACCEPTS: [FONTNAME | ‘serif’ | ‘sans-serif’ | ‘cursive’ | ‘fantasy’ |
      ‘monospace’ ]
  `set_font_properties`(fp)

    alias for set_fontproperties

  `set_fontname`(fontname)

    alias for set_family

  `set_fontproperties`(fp)

    Set the font properties that control the text. fp must be a `matplotlib.font_manager.FontProperties` object.

    ACCEPTS: a `matplotlib.font_manager.FontProperties` instance

  `set_fontsize`(fontsize)

    alias for set_size

  `set_fontstretch`(stretch)

    alias for set_stretch

  `set_fontstyle`(fontstyle)

    alias for set_style

  `set_fontvariant`(variant)

    alias for set_variant

  `set_fontweight`(weight)

    alias for set_weight

  `set_ha`(align)

    alias for set_horizontalalignment

  `set_horizontalalignment`(align)

    Set the horizontal alignment to one of

    ACCEPTS: [ ‘center’ | ‘right’ | ‘left’ ]

  `set_linespacing`(spacing)

    Set the line spacing as a multiple of the font size. Default is 1.2.

    ACCEPTS: float (multiple of font size)

  `set_ma`(align)

    alias for set_verticalalignment

  `set_multialignment`(align)

    Set the alignment for multiple lines layout. The layout of the bounding box of all the lines is determined bu the horizontalalignment and verticalalignment properties, but the multiline text within that box can be

    ACCEPTS: [‘left’ | ‘right’ | ‘center’ ]

  `set_name`(fontname)

    alias for set_family

  `set_position`(xy)

    Set the (x, y) position of the text

    ACCEPTS: (x,y)

  `set_rotation`(s)

    Set the rotation of the text

    ACCEPTS: [ angle in degrees | ‘vertical’ | ‘horizontal’ ]

  `set_rotation_mode`(m)

    set text rotation mode. If “anchor”, the un-rotated text will first aligned according to their ha and va, and then will be rotated with the alignement reference point as a origin. If None (default), the text will be rotated first then will be aligned.

  `set_size`(fontsize)

    Set the font size. May be either a size string, relative to the default font size, or an absolute font size in points.

    ACCEPTS: [size in points | ‘xx-small’ | ‘x-small’ | ‘small’ |
      ‘medium’ | ‘large’ | ‘x-large’ | ‘xx-large’ ]
  `set_stretch`(stretch)

    Set the font stretch (horizontal condensation or expansion).

    ACCEPTS: [a numeric value in range 0-1000 | ‘ultra-condensed’ |
      ‘extra-condensed’ | ‘condensed’ | ‘semi-condensed’ | ‘normal’ | ‘semi-expanded’ | ‘expanded’ | ‘extra-expanded’ | ‘ultra-expanded’ ]
  `set_style`(fontstyle)

    Set the font style.

    ACCEPTS: [ ‘normal’ | ‘italic’ | ‘oblique’]

  `set_text`(s)

    Set the text string s

    It may contain newlines (`\n`) or math in LaTeX syntax.

    ACCEPTS: string or anything printable with ‘%s’ conversion.

  `set_usetex`(usetex)

    Set this `Text` object to render using TeX (or not).

    If `None` is given, the option will be reset to use the value of `rcParams['text.usetex']`

  `set_va`(align)

    alias for set_verticalalignment

  `set_variant`(variant)

    Set the font variant, either ‘normal’ or ‘small-caps’.

    ACCEPTS: [ ‘normal’ | ‘small-caps’ ]

  `set_verticalalignment`(align)

    Set the vertical alignment

    ACCEPTS: [ ‘center’ | ‘top’ | ‘bottom’ | ‘baseline’ ]

  `set_weight`(weight)

    Set the font weight.

    ACCEPTS: [a numeric value in range 0-1000 | ‘ultralight’ | ‘light’ |
      ‘normal’ | ‘regular’ | ‘book’ | ‘medium’ | ‘roman’ | ‘semibold’ | ‘demibold’ | ‘demi’ | ‘bold’ | ‘heavy’ | ‘extra bold’ | ‘black’ ]
  `set_wrap`(wrap)

    Sets the wrapping state for the text.

  `set_x`(x)

    Set the x position of the text

    ACCEPTS: float

  `set_y`(y)

    Set the y position of the text

    ACCEPTS: float

  `update`(kwargs)

    Update properties from a dictionary.

  `update_bbox_position_size`(renderer)

    Update the location and the size of the bbox. This method should be used when the position and size of the bbox needs to be updated before actually drawing the bbox.

  `update_from`(other)

    Copy properties from other to self

  `zorder` = 3

class `matplotlib.text.``TextWithDash`(x=0, y=0, text=”, color=None, verticalalignment=’center’, horizontalalignment=’center’, multialignment=None, fontproperties=None, rotation=None, linespacing=None, dashlength=0.0, dashdirection=0, dashrotation=None, dashpad=3, dashpush=0)

  Bases: `matplotlib.text.Text`

  This is basically a `Text` with a dash (drawn with a `Line2D`) before/after it. It is intended to be a drop-in replacement for `Text`, and should behave identically to it when dashlength = 0.0.

  The dash always comes between the point specified by `set_position()` and the text. When a dash exists, the text alignment arguments (horizontalalignment, verticalalignment) are ignored.

  dashlength is the length of the dash in canvas units. (default = 0.0).

  dashdirection is one of 0 or 1, where 0 draws the dash after the text and 1 before. (default = 0).

  dashrotation specifies the rotation of the dash, and should generally stay None. In this case `get_dashrotation()` returns `get_rotation()`. (i.e., the dash takes its rotation from the text’s rotation). Because the text center is projected onto the dash, major deviations in the rotation cause what may be considered visually unappealing results. (default = None)

  dashpad is a padding length to add (or subtract) space between the text and the dash, in canvas units. (default = 3)

  dashpush “pushes” the dash and text away from the point specified by `set_position()` by the amount in canvas units. (default = 0)

  Note

  The alignment of the two objects is based on the bounding box of the `Text`, as obtained by `get_window_extent()`. This, in turn, appears to depend on the font metrics as given by the rendering backend. Hence the quality of the “centering” of the label text with respect to the dash varies depending on the backend used.

  Note

  I’m not sure that I got the `get_window_extent()` right, or whether that’s sufficient for providing the object bounding box.

  `draw`(renderer)

    Draw the `TextWithDash` object to the given renderer.

  `get_dashdirection`()

    Get the direction dash. 1 is before the text and 0 is after.

  `get_dashlength`()

    Get the length of the dash.

  `get_dashpad`()

    Get the extra spacing between the dash and the text, in canvas units.

  `get_dashpush`()

    Get the extra spacing between the dash and the specified text position, in canvas units.

  `get_dashrotation`()

    Get the rotation of the dash in degrees.

  `get_figure`()

    return the figure instance the artist belongs to

  `get_position`()

    Return the position of the text as a tuple (x, y)

  `get_prop_tup`(renderer=None)

    Return a hashable tuple of properties.

    Not intended to be human readable, but useful for backends who want to cache derived information about text (e.g., layouts) and need to know if the text has changed.

  `get_unitless_position`()

    Return the unitless position of the text as a tuple (x, y)

  `get_window_extent`(renderer=None)

    Return a `Bbox` object bounding the text, in display units.

    In addition to being used internally, this is useful for specifying clickable regions in a png file on a web page.

    renderer defaults to the _renderer attribute of the text object. This is not assigned until the first execution of `draw()`, so you must use this kwarg if you want to call `get_window_extent()` prior to the first `draw()`. For getting web page regions, it is simpler to call the method after saving the figure.

  `set_dashdirection`(dd)

    Set the direction of the dash following the text. 1 is before the text and 0 is after. The default is 0, which is what you’d want for the typical case of ticks below and on the left of the figure.

    ACCEPTS: int (1 is before, 0 is after)

  `set_dashlength`(dl)

    Set the length of the dash.

    ACCEPTS: float (canvas units)

  `set_dashpad`(dp)

    Set the “pad” of the TextWithDash, which is the extra spacing between the dash and the text, in canvas units.

    ACCEPTS: float (canvas units)

  `set_dashpush`(dp)

    Set the “push” of the TextWithDash, which is the extra spacing between the beginning of the dash and the specified position.

    ACCEPTS: float (canvas units)

  `set_dashrotation`(dr)

    Set the rotation of the dash, in degrees

    ACCEPTS: float (degrees)

  `set_figure`(fig)

    Set the figure instance the artist belong to.

    ACCEPTS: a `matplotlib.figure.Figure` instance

  `set_position`(xy)

    Set the (x, y) position of the `TextWithDash`.

    ACCEPTS: (x, y)

  `set_transform`(t)

    Set the `matplotlib.transforms.Transform` instance used by this artist.

    ACCEPTS: a `matplotlib.transforms.Transform` instance

  `set_x`(x)

    Set the x position of the `TextWithDash`.

    ACCEPTS: float

  `set_y`(y)

    Set the y position of the `TextWithDash`.

    ACCEPTS: float

  `update_coords`(renderer)

    Computes the actual x, y coordinates for text based on the input x, y and the dashlength. Since the rotation is with respect to the actual canvas’s coordinates we need to map back and forth.

`matplotlib.text.``get_rotation`(rotation)

  Return the text angle as float. The returned angle is between 0 and 360 deg.

  rotation may be ‘horizontal’, ‘vertical’, or a numeric value in degrees.