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

JavaScript Figure Reference: layout.annotations

  • annotations
    Parent: layout
    Type: array of object where each object 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
      Parent: layout.annotations[]
      Type: boolean
      Default: true

      Determines whether or not this annotation is visible.

    • text
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      Type: angle
      Default: 0

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

    • font
      Parent: layout.annotations[]
      Type: object containing one or more of the keys listed below.

      Sets the annotation text font.

      • family
        Parent: layout.annotations[].font
        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
        Parent: layout.annotations[].font
        Type: number greater than or equal to 1
      • color
        Parent: layout.annotations[].font
        Type: color
    • width
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      Type: number between or equal to 0 and 1
      Default: 1

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

    • align
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      Type: color
      Default: "rgba(0,0,0,0)"

      Sets the background color of the annotation.

    • bordercolor
      Parent: layout.annotations[]
      Type: color
      Default: "rgba(0,0,0,0)"

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

    • borderpad
      Parent: layout.annotations[]
      Type: number greater than or equal to 0
      Default: 1

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

    • borderwidth
      Parent: layout.annotations[]
      Type: number greater than or equal to 0
      Default: 1

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

    • showarrow
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      Type: color

      Sets the color of the annotation arrow.

    • arrowhead
      Parent: layout.annotations[]
      Type: integer between or equal to 0 and 8
      Default: 1

      Sets the end annotation arrow head style.

    • startarrowhead
      Parent: layout.annotations[]
      Type: integer between or equal to 0 and 8
      Default: 1

      Sets the start annotation arrow head style.

    • arrowside
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      Type: number greater than or equal to 0.1

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

    • standoff
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      Type: number
      Default: 0

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

    • clicktoshow
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      Type: string

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

    • hoverlabel
      Parent: layout.annotations[]
      Type: object containing one or more of the keys listed below.
      • bgcolor
        Parent: layout.annotations[].hoverlabel
        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
        Parent: layout.annotations[].hoverlabel
        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
        Parent: layout.annotations[].hoverlabel
        Type: object 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
          Parent: layout.annotations[].hoverlabel.font
          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
          Parent: layout.annotations[].hoverlabel.font
          Type: number greater than or equal to 1
        • color
          Parent: layout.annotations[].hoverlabel.font
          Type: color
    • captureevents
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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
      Parent: layout.annotations[]
      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`.