Black Lives Matter. Please consider donating to Black Girls Code today.

Python Figure Reference: layout.annotations

  • annotations
    Code: fig.update_annotations(...)
    Type: list of dict where each dict has one or more of the keys listed below.
    An annotation is a text element that can be placed anywhere in the plot. It can be positioned with respect to relative coordinates in the plot or with respect to the actual data coordinates of the graph. Annotations can be shown with or without an arrow.
    • visible
      Code: fig.update_annotations(visible=<VALUE>)
      Type: boolean
      Default: True

      Determines whether or not this annotation is visible.

    • text
      Code: fig.update_annotations(text=<VALUE>)
      Type: string

      Sets the text associated with this annotation. Plotly uses a subset of HTML tags to do things like newline (<br>), bold (<b></b>), italics (<i></i>), hyperlinks (<a href='...'></a>). Tags <em>, <sup>, <sub> <span> are also supported.

    • textangle
      Code: fig.update_annotations(textangle=<VALUE>)
      Type: angle
      Default: 0

      Sets the angle at which the `text` is drawn with respect to the horizontal.

    • font
      Code: fig.update_annotations(font=dict(...))
      Type: dict containing one or more of the keys listed below.

      Sets the annotation text font.

      • family
        Code: fig.update_annotations(font_family=<VALUE>)
        Type: string

        HTML font family - the typeface that will be applied by the web browser. The web browser will only be able to apply a font if it is available on the system which it operates. Provide multiple font families, separated by commas, to indicate the preference in which to apply fonts if they aren't available on the system. The Chart Studio Cloud (at https://chart-studio.plotly.com or on-premise) generates images on a server, where only a select number of fonts are installed and supported. These include "Arial", "Balto", "Courier New", "Droid Sans",, "Droid Serif", "Droid Sans Mono", "Gravitas One", "Old Standard TT", "Open Sans", "Overpass", "PT Sans Narrow", "Raleway", "Times New Roman".

      • size
        Code: fig.update_annotations(font_size=<VALUE>)
        Type: number greater than or equal to 1
      • color
        Code: fig.update_annotations(font_color=<VALUE>)
        Type: color
    • width
      Code: fig.update_annotations(width=<VALUE>)
      Type: number greater than or equal to 1

      Sets an explicit width for the text box. null (default) lets the text set the box width. Wider text will be clipped. There is no automatic wrapping; use <br> to start a new line.

    • height
      Code: fig.update_annotations(height=<VALUE>)
      Type: number greater than or equal to 1

      Sets an explicit height for the text box. null (default) lets the text set the box height. Taller text will be clipped.

    • opacity
      Code: fig.update_annotations(opacity=<VALUE>)
      Type: number between or equal to 0 and 1
      Default: 1

      Sets the opacity of the annotation (text + arrow).

    • align
      Code: fig.update_annotations(align=<VALUE>)
      Type: enumerated , one of ( "left" | "center" | "right" )
      Default: "center"

      Sets the horizontal alignment of the `text` within the box. Has an effect only if `text` spans two or more lines (i.e. `text` contains one or more <br> HTML tags) or if an explicit width is set to override the text width.

    • valign
      Code: fig.update_annotations(valign=<VALUE>)
      Type: enumerated , one of ( "top" | "middle" | "bottom" )
      Default: "middle"

      Sets the vertical alignment of the `text` within the box. Has an effect only if an explicit height is set to override the text height.

    • bgcolor
      Code: fig.update_annotations(bgcolor=<VALUE>)
      Type: color
      Default: "rgba(0,0,0,0)"

      Sets the background color of the annotation.

    • bordercolor
      Code: fig.update_annotations(bordercolor=<VALUE>)
      Type: color
      Default: "rgba(0,0,0,0)"

      Sets the color of the border enclosing the annotation `text`.

    • borderpad
      Code: fig.update_annotations(borderpad=<VALUE>)
      Type: number greater than or equal to 0
      Default: 1

      Sets the padding (in px) between the `text` and the enclosing border.

    • borderwidth
      Code: fig.update_annotations(borderwidth=<VALUE>)
      Type: number greater than or equal to 0
      Default: 1

      Sets the width (in px) of the border enclosing the annotation `text`.

    • showarrow
      Code: fig.update_annotations(showarrow=<VALUE>)
      Type: boolean
      Default: True

      Determines whether or not the annotation is drawn with an arrow. If "True", `text` is placed near the arrow's tail. If "False", `text` lines up with the `x` and `y` provided.

    • arrowcolor
      Code: fig.update_annotations(arrowcolor=<VALUE>)
      Type: color

      Sets the color of the annotation arrow.

    • arrowhead
      Code: fig.update_annotations(arrowhead=<VALUE>)
      Type: integer between or equal to 0 and 8
      Default: 1

      Sets the end annotation arrow head style.

    • startarrowhead
      Code: fig.update_annotations(startarrowhead=<VALUE>)
      Type: integer between or equal to 0 and 8
      Default: 1

      Sets the start annotation arrow head style.

    • arrowside
      Code: fig.update_annotations(arrowside=<VALUE>)
      Type: flaglist string. Any combination of "end", "start" joined with a "+" OR "none".
      Examples: "end", "start", "end+start", "none"
      Default: "end"

      Sets the annotation arrow head position.

    • arrowsize
      Code: fig.update_annotations(arrowsize=<VALUE>)
      Type: number greater than or equal to 0.3
      Default: 1

      Sets the size of the end annotation arrow head, relative to `arrowwidth`. A value of 1 (default) gives a head about 3x as wide as the line.

    • startarrowsize
      Code: fig.update_annotations(startarrowsize=<VALUE>)
      Type: number greater than or equal to 0.3
      Default: 1

      Sets the size of the start annotation arrow head, relative to `arrowwidth`. A value of 1 (default) gives a head about 3x as wide as the line.

    • arrowwidth
      Code: fig.update_annotations(arrowwidth=<VALUE>)
      Type: number greater than or equal to 0.1

      Sets the width (in px) of annotation arrow line.

    • standoff
      Code: fig.update_annotations(standoff=<VALUE>)
      Type: number greater than or equal to 0
      Default: 0

      Sets a distance, in pixels, to move the end arrowhead away from the position it is pointing at, for example to point at the edge of a marker independent of zoom. Note that this shortens the arrow from the `ax` / `ay` vector, in contrast to `xshift` / `yshift` which moves everything by this amount.

    • startstandoff
      Code: fig.update_annotations(startstandoff=<VALUE>)
      Type: number greater than or equal to 0
      Default: 0

      Sets a distance, in pixels, to move the start arrowhead away from the position it is pointing at, for example to point at the edge of a marker independent of zoom. Note that this shortens the arrow from the `ax` / `ay` vector, in contrast to `xshift` / `yshift` which moves everything by this amount.

    • ax
      Code: fig.update_annotations(ax=<VALUE>)
      Type: number or categorical coordinate string

      Sets the x component of the arrow tail about the arrow head. If `axref` is `pixel`, a positive (negative) component corresponds to an arrow pointing from right to left (left to right). If `axref` is not `pixel` and is exactly the same as `xref`, this is an absolute value on that axis, like `x`, specified in the same coordinates as `xref`.

    • ay
      Code: fig.update_annotations(ay=<VALUE>)
      Type: number or categorical coordinate string

      Sets the y component of the arrow tail about the arrow head. If `ayref` is `pixel`, a positive (negative) component corresponds to an arrow pointing from bottom to top (top to bottom). If `ayref` is not `pixel` and is exactly the same as `yref`, this is an absolute value on that axis, like `y`, specified in the same coordinates as `yref`.

    • axref
      Code: fig.update_annotations(axref=<VALUE>)
      Type: enumerated , one of ( "pixel" | "/^x([2-9]|[1-9][0-9]+)?( domain)?$/" )
      Default: "pixel"

      Indicates in what coordinates the tail of the annotation (ax,ay) is specified. If set to a ax axis id (e.g. "ax" or "ax2"), the `ax` position refers to a ax coordinate. If set to "paper", the `ax` position refers to the distance from the left of the plotting area in normalized coordinates where "0" ("1") corresponds to the left (right). If set to a ax axis ID followed by "domain" (separated by a space), the position behaves like for "paper", but refers to the distance in fractions of the domain length from the left of the domain of that axis: e.g., "ax2 domain" refers to the domain of the second ax axis and a ax position of 0.5 refers to the point between the left and the right of the domain of the second ax axis. In order for absolute positioning of the arrow to work, "axref" must be exactly the same as "xref", otherwise "axref" will revert to "pixel" (explained next). For relative positioning, "axref" can be set to "pixel", in which case the "ax" value is specified in pixels relative to "x". Absolute positioning is useful for trendline annotations which should continue to indicate the correct trend when zoomed. Relative positioning is useful for specifying the text offset for an annotated point.

    • ayref
      Code: fig.update_annotations(ayref=<VALUE>)
      Type: enumerated , one of ( "pixel" | "/^y([2-9]|[1-9][0-9]+)?( domain)?$/" )
      Default: "pixel"

      Indicates in what coordinates the tail of the annotation (ax,ay) is specified. If set to a ay axis id (e.g. "ay" or "ay2"), the `ay` position refers to a ay coordinate. If set to "paper", the `ay` position refers to the distance from the bottom of the plotting area in normalized coordinates where "0" ("1") corresponds to the bottom (top). If set to a ay axis ID followed by "domain" (separated by a space), the position behaves like for "paper", but refers to the distance in fractions of the domain length from the bottom of the domain of that axis: e.g., "ay2 domain" refers to the domain of the second ay axis and a ay position of 0.5 refers to the point between the bottom and the top of the domain of the second ay axis. In order for absolute positioning of the arrow to work, "ayref" must be exactly the same as "yref", otherwise "ayref" will revert to "pixel" (explained next). For relative positioning, "ayref" can be set to "pixel", in which case the "ay" value is specified in pixels relative to "y". Absolute positioning is useful for trendline annotations which should continue to indicate the correct trend when zoomed. Relative positioning is useful for specifying the text offset for an annotated point.

    • xref
      Code: fig.update_annotations(xref=<VALUE>)
      Type: enumerated , one of ( "paper" | "/^x([2-9]|[1-9][0-9]+)?( domain)?$/" )

      Sets the annotation's x coordinate axis. If set to a x axis id (e.g. "x" or "x2"), the `x` position refers to a x coordinate. If set to "paper", the `x` position refers to the distance from the left of the plotting area in normalized coordinates where "0" ("1") corresponds to the left (right). If set to a x axis ID followed by "domain" (separated by a space), the position behaves like for "paper", but refers to the distance in fractions of the domain length from the left of the domain of that axis: e.g., "x2 domain" refers to the domain of the second x axis and a x position of 0.5 refers to the point between the left and the right of the domain of the second x axis.

    • x
      Code: fig.update_annotations(x=<VALUE>)
      Type: number or categorical coordinate string

      Sets the annotation's x position. If the axis `type` is "log", then you must take the log of your desired range. If the axis `type` is "date", it should be date strings, like date data, though Date objects and unix milliseconds will be accepted and converted to strings. If the axis `type` is "category", it should be numbers, using the scale where each category is assigned a serial number from zero in the order it appears.

    • xanchor
      Code: fig.update_annotations(xanchor=<VALUE>)
      Type: enumerated , one of ( "auto" | "left" | "center" | "right" )
      Default: "auto"

      Sets the text box's horizontal position anchor This anchor binds the `x` position to the "left", "center" or "right" of the annotation. For example, if `x` is set to 1, `xref` to "paper" and `xanchor` to "right" then the right-most portion of the annotation lines up with the right-most edge of the plotting area. If "auto", the anchor is equivalent to "center" for data-referenced annotations or if there is an arrow, whereas for paper-referenced with no arrow, the anchor picked corresponds to the closest side.

    • xshift
      Code: fig.update_annotations(xshift=<VALUE>)
      Type: number
      Default: 0

      Shifts the position of the whole annotation and arrow to the right (positive) or left (negative) by this many pixels.

    • yref
      Code: fig.update_annotations(yref=<VALUE>)
      Type: enumerated , one of ( "paper" | "/^y([2-9]|[1-9][0-9]+)?( domain)?$/" )

      Sets the annotation's y coordinate axis. If set to a y axis id (e.g. "y" or "y2"), the `y` position refers to a y coordinate. If set to "paper", the `y` position refers to the distance from the bottom of the plotting area in normalized coordinates where "0" ("1") corresponds to the bottom (top). If set to a y axis ID followed by "domain" (separated by a space), the position behaves like for "paper", but refers to the distance in fractions of the domain length from the bottom of the domain of that axis: e.g., "y2 domain" refers to the domain of the second y axis and a y position of 0.5 refers to the point between the bottom and the top of the domain of the second y axis.

    • y
      Code: fig.update_annotations(y=<VALUE>)
      Type: number or categorical coordinate string

      Sets the annotation's y position. If the axis `type` is "log", then you must take the log of your desired range. If the axis `type` is "date", it should be date strings, like date data, though Date objects and unix milliseconds will be accepted and converted to strings. If the axis `type` is "category", it should be numbers, using the scale where each category is assigned a serial number from zero in the order it appears.

    • yanchor
      Code: fig.update_annotations(yanchor=<VALUE>)
      Type: enumerated , one of ( "auto" | "top" | "middle" | "bottom" )
      Default: "auto"

      Sets the text box's vertical position anchor This anchor binds the `y` position to the "top", "middle" or "bottom" of the annotation. For example, if `y` is set to 1, `yref` to "paper" and `yanchor` to "top" then the top-most portion of the annotation lines up with the top-most edge of the plotting area. If "auto", the anchor is equivalent to "middle" for data-referenced annotations or if there is an arrow, whereas for paper-referenced with no arrow, the anchor picked corresponds to the closest side.

    • yshift
      Code: fig.update_annotations(yshift=<VALUE>)
      Type: number
      Default: 0

      Shifts the position of the whole annotation and arrow up (positive) or down (negative) by this many pixels.

    • clicktoshow
      Code: fig.update_annotations(clicktoshow=<VALUE>)
      Type: enumerated , one of ( False | "onoff" | "onout" )

      Makes this annotation respond to clicks on the plot. If you click a data point that exactly matches the `x` and `y` values of this annotation, and it is hidden (visible: False), it will appear. In "onoff" mode, you must click the same point again to make it disappear, so if you click multiple points, you can show multiple annotations. In "onout" mode, a click anywhere else in the plot (on another data point or not) will hide this annotation. If you need to show/hide this annotation in response to different `x` or `y` values, you can set `xclick` and/or `yclick`. This is useful for example to label the side of a bar. To label markers though, `standoff` is preferred over `xclick` and `yclick`.

    • xclick
      Code: fig.update_annotations(xclick=<VALUE>)
      Type: number or categorical coordinate string

      Toggle this annotation when clicking a data point whose `x` value is `xclick` rather than the annotation's `x` value.

    • yclick
      Code: fig.update_annotations(yclick=<VALUE>)
      Type: number or categorical coordinate string

      Toggle this annotation when clicking a data point whose `y` value is `yclick` rather than the annotation's `y` value.

    • hovertext
      Code: fig.update_annotations(hovertext=<VALUE>)
      Type: string

      Sets text to appear when hovering over this annotation. If omitted or blank, no hover label will appear.

    • hoverlabel
      Code: fig.update_annotations(hoverlabel=dict(...))
      Type: dict containing one or more of the keys listed below.
      • bgcolor
        Code: fig.update_annotations(hoverlabel_bgcolor=<VALUE>)
        Type: color

        Sets the background color of the hover label. By default uses the annotation's `bgcolor` made opaque, or white if it was transparent.

      • bordercolor
        Code: fig.update_annotations(hoverlabel_bordercolor=<VALUE>)
        Type: color

        Sets the border color of the hover label. By default uses either dark grey or white, for maximum contrast with `hoverlabel.bgcolor`.

      • font
        Code: fig.update_annotations(hoverlabel_font=dict(...))
        Type: dict containing one or more of the keys listed below.

        Sets the hover label text font. By default uses the global hover font and size, with color from `hoverlabel.bordercolor`.

        • family
          Code: fig.update_annotations(hoverlabel_font_family=<VALUE>)
          Type: string

          HTML font family - the typeface that will be applied by the web browser. The web browser will only be able to apply a font if it is available on the system which it operates. Provide multiple font families, separated by commas, to indicate the preference in which to apply fonts if they aren't available on the system. The Chart Studio Cloud (at https://chart-studio.plotly.com or on-premise) generates images on a server, where only a select number of fonts are installed and supported. These include "Arial", "Balto", "Courier New", "Droid Sans",, "Droid Serif", "Droid Sans Mono", "Gravitas One", "Old Standard TT", "Open Sans", "Overpass", "PT Sans Narrow", "Raleway", "Times New Roman".

        • size
          Code: fig.update_annotations(hoverlabel_font_size=<VALUE>)
          Type: number greater than or equal to 1
        • color
          Code: fig.update_annotations(hoverlabel_font_color=<VALUE>)
          Type: color
    • captureevents
      Code: fig.update_annotations(captureevents=<VALUE>)
      Type: boolean

      Determines whether the annotation text box captures mouse move and click events, or allows those events to pass through to data points in the plot that may be behind the annotation. By default `captureevents` is "False" unless `hovertext` is provided. If you use the event `plotly_clickannotation` without `hovertext` you must explicitly enable `captureevents`.

    • name
      Code: fig.update_annotations(name=<VALUE>)
      Type: string

      When used in a template, named items are created in the output figure in addition to any items the figure already has in this array. You can modify these items in the output figure by making your own item with `templateitemname` matching this `name` alongside your modifications (including `visible: False` or `enabled: False` to hide it). Has no effect outside of a template.

    • templateitemname
      Code: fig.update_annotations(templateitemname=<VALUE>)
      Type: string

      Used to refer to a named item in this array in the template. Named items from the template will be created even without a matching item in the input figure, but you can modify one by making an item with `templateitemname` matching its `name`, alongside your modifications (including `visible: False` or `enabled: False` to hide it). If there is no template or no matching item, this item will be hidden unless you explicitly show it with `visible: True`.