image attributes

Images: pixel colors (RGB, RGBA or HSL components, or an encoded picture) drawn as one texture on the axes, with pixel hover.

• Categories: cartesian, 2dMap, noSortingByValue
• Plotly equivalent: image
• Guide: image chart page
• Used in examples: demos/science-basics/spectra, heatmap/interaction, image/dates, image/float-range, image/hsl, image/rgb, image/source

Generated from the attribute schema (51 entries). Machine-readable: plot-schema.json.

Attribute tree

• type
• visible
• name
• uid
• showlegend
• legend
• legendgroup
• hovertext
• hoverinfo
• hovertemplate
• hoverlabel

  • bgcolor
  • bordercolor
  • font

    • family
    • size
    • color
  • align
  • namelength
• selectedpoints
• legendrank
• legendwidth
• legendgrouptitle

  • text
  • font

    • family
    • size
    • color
    • weight
    • style
• opacity
• meta
• customdata
• ids
• dataset
• uirevision
• styleRules
• xaxis
• yaxis
• source
• z
• colormodel
• zmin
• zmax
• zsmooth
• x0
• y0
• dx
• dy
• text
• zorder

type string

Trace type, e.g. 'scatter'. Defaults to 'scatter'.

• Type: string (non-empty)
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

visible enumerated

Whether the trace is drawn. legendonly hides it but keeps its (toggleable) legend entry.

• Type: enumerated
• Values: true | false | "legendonly"
• Default: true
• Array OK: no
• Edit type: calc
• Animatable: no

name string

Trace name shown in the legend and hover labels. Defaults to trace N.

• Type: string
• Default: none
• Array OK: no
• Edit type: legend+plot
• Animatable: no

uid string

Stable identity used to match traces across updates, so reordered traces are moved instead of rebuilt.

• Type: string
• Default: none
• Array OK: no
• Edit type: plot
• Animatable: no

showlegend boolean

Whether this trace has a legend entry.

• Type: boolean
• Default: true
• Array OK: no
• Edit type: legend+layout
• Animatable: no

legend subplotid

The legend this trace's item is shown in: 'legend' (layout.legend), 'legend2' (layout.legend2), ….

• Type: subplotid (legend, legend2, legend3, …)
• Default: "legend"
• Array OK: no
• Edit type: legend+layout
• Animatable: no

legendgroup string

Traces in the same legend group toggle together.

• Type: string
• Default: ""
• Array OK: no
• Edit type: legend
• Animatable: no

hovertext data_array

Hover text per pixel (2D like z); takes precedence over text.

• Type: data_array (array or typed array)
• Default: none
• Array OK: no
• Edit type: plot
• Animatable: no

hoverinfo flaglist

Which fields hover labels show: z is the pixel's components as given, color the color they make in the color model (RGB: [r, g, b]).

• Type: flaglist
• Flags: "x", "y", "z", "color", "name", "text" (combine with +)
• Also accepts: "all" | "none" | "skip"
• Default: "x+y+z+text+name"
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hovertemplate string

Template for hover labels: %{x}, %{y}, %{z} (the pixel, %{z[0]} … its components), %{color} (scaled color, %{color[0]} …), %{colormodel}.

• Type: string
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hoverlabel

Hover label style for this trace. Unset fields fall back to layout.hoverlabel (so there are no trace-level defaults).

• Type: object
• Edit type: none

hoverlabel.bgcolor color

Label background. Default: the point color.

• Type: color
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hoverlabel.bordercolor color

Label border. Default: contrasting with the background.

• Type: color
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hoverlabel.font

Label font.

• Type: object
• Edit type: none

hoverlabel.font.family string

Font family.

• Type: string
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hoverlabel.font.size number

Font size in px.

• Type: number ≥ 1
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hoverlabel.font.color color

Font color.

• Type: color
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hoverlabel.align enumerated

Text alignment inside labels.

• Type: enumerated
• Values: "left" | "right" | "auto"
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

hoverlabel.namelength integer

Characters of the trace name shown (-1: all, 0: none).

• Type: integer ≥ -1
• Default: none
• Array OK: yes (one value per point)
• Edit type: none
• Animatable: no

selectedpoints any

Indices of the selected points (set by box/lasso selection, or programmatically). null clears the selection.

• Type: any
• Default: none
• Array OK: no
• Edit type: style
• Animatable: no

legendrank number

Sort key for legend entries: lower ranks come first (top, or left). Ties keep trace order; traces default to 1000.

• Type: number
• Default: 1000
• Array OK: no
• Edit type: legend
• Animatable: no

legendwidth number

Width of this trace's item in horizontal legends, overriding legend.entrywidth (same units). Default: its text's.

• Type: number ≥ 0
• Default: none
• Array OK: no
• Edit type: legend
• Animatable: no

legendgrouptitle

Title of the legend group this trace belongs to.

• Type: object
• Edit type: legend

legendgrouptitle.text string

Title heading this trace's legend group.

• Type: string
• Default: ""
• Array OK: no
• Edit type: legend
• Animatable: no

legendgrouptitle.font

Group title font. Unset fields come from legend.grouptitlefont.

• Type: object
• Edit type: legend

legendgrouptitle.font.family string

Font family.

• Type: string
• Default: none
• Array OK: no
• Edit type: legend
• Animatable: no

legendgrouptitle.font.size number

Font size in px.

• Type: number ≥ 1
• Default: none
• Array OK: no
• Edit type: legend
• Animatable: no

legendgrouptitle.font.color color

Font color.

• Type: color
• Default: none
• Array OK: no
• Edit type: legend
• Animatable: no

legendgrouptitle.font.weight integer

Font weight: a CSS numeric weight (1–1000), normal or bold.

• Type: integer from 1 to 1000, or "normal" | "bold"
• Default: none
• Array OK: no
• Edit type: legend
• Animatable: no

legendgrouptitle.font.style enumerated

Font style.

• Type: enumerated
• Values: "normal" | "italic"
• Default: none
• Array OK: no
• Edit type: legend
• Animatable: no

opacity number

Opacity of the whole trace.

• Type: number from 0 to 1
• Default: 1
• Array OK: no
• Edit type: style
• Animatable: yes

meta any

Arbitrary user data, available in text templates as %{meta}.

• Type: any
• Default: none
• Array OK: yes (one value per point)
• Edit type: plot
• Animatable: no

customdata data_array

Per-point user data, returned in events and available in hover templates.

• Type: data_array (array or typed array)
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

ids data_array

Per-point ids used to match points across animation frames.

• Type: data_array (array or typed array)
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

dataset string

Name of a figure-level dataset (figure.datasets). Data arrays, and per-point attributes whose values cannot start with @ (such as colors and sizes), may then reference its columns as '@column'; on string attributes such as text, '@…' stays literal text.

• Type: string (non-empty)
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

uirevision any

While unchanged, user interaction state for this trace (legend visibility, selections) is kept across updates.

• Type: any
• Default: none
• Array OK: no
• Edit type: none
• Animatable: no

styleRules any

Conditional per-point styling as JSON (plan E8.5): [{ when: { y: { gt: 10 } }, set: { 'marker.color': 'gold' } }]. when tests fields of the point ('y', 'customdata[1]', 'pointNumber', …) with eq, ne, gt, gte, lt, lte, in, nin, between, regex, and, or and not; set gives per-point (arrayOk) attributes a value on the matching points. Later rules win; other points keep the trace's own value.

• Type: any
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

xaxis subplotid

The x axis this trace is plotted against: 'x' → layout.xaxis, 'x2' → layout.xaxis2.

• Type: subplotid (x, x2, x3, …)
• Default: "x"
• Array OK: no
• Edit type: calc
• Animatable: no

yaxis subplotid

The y axis this trace is plotted against: 'y' → layout.yaxis, 'y2' → layout.yaxis2.

• Type: subplotid (y, y2, y3, …)
• Default: "y"
• Array OK: no
• Edit type: calc
• Animatable: no

source string

The picture as a base64 data URI ('data:image/png;base64,…'; PNG, JPEG, GIF, WebP or BMP), used when z is not given. Other URLs are ignored, as in Plotly.

• Type: string
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

z data_array

Pixel colors: z[row][column] is an array of color components in colormodel (e.g. [r, g, b]). Row 0 is drawn at y0, at the top by default.

• Type: data_array (array or typed array)
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

colormodel enumerated

How z components are read: 'rgb' (default), 'rgba' (alpha 0–1), 'rgba256' (alpha 0–255; always used for source), 'hsl' or 'hsla'.

• Type: enumerated
• Values: "rgb" | "rgba" | "rgba256" | "hsl" | "hsla"
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

zmin info_array

Per component, the z value mapped to the first value of the color model's range (0–255 for r, g, b; 0–1 for alpha, or 0–255 with rgba256; 0–360 for hue; 0–100 for saturation and lightness). Default: that range, so values are used as they are.

• Type: info_array [number, number, number, number], any length
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

zmax info_array

Per component, the z value mapped to the last value of the color model's range (0–255 for r, g, b; 0–1 for alpha, or 0–255 with rgba256; 0–360 for hue; 0–100 for saturation and lightness). Default: that range, so values are used as they are.

• Type: info_array [number, number, number, number], any length
• Default: none
• Array OK: no
• Edit type: calc
• Animatable: no

zsmooth enumerated

Pixel smoothing: none (false, square pixels) or 'fast' (bilinear, the GPU's linear filtering).

• Type: enumerated
• Values: "fast" | false
• Default: false
• Array OK: no
• Edit type: style
• Animatable: no

x0 any

X coordinate of the center of the first pixel column.

• Type: any
• Default: 0
• Array OK: no
• Edit type: calc
• Animatable: no

y0 any

Y coordinate of the center of the first pixel row.

• Type: any
• Default: 0
• Array OK: no
• Edit type: calc
• Animatable: no

dx number

Pixel width in x units.

• Type: number
• Default: 1
• Array OK: no
• Edit type: calc
• Animatable: no

dy number

Pixel height in y units.

• Type: number
• Default: 1
• Array OK: no
• Edit type: calc
• Animatable: no

text data_array

Text per pixel (2D like z), shown in hover labels.

• Type: data_array (array or typed array)
• Default: none
• Array OK: no
• Edit type: plot
• Animatable: no

zorder integer

Stacking order among the traces of a subplot: higher is drawn on top. At equal zorder, images draw below every other trace type (Plotly’s layer order).

• Type: integer
• Default: 0
• Array OK: no
• Edit type: plot
• Animatable: no