Graph Examples and Reference

The dcc.Graph component can be used to render any plotly-powered data visualization,
passed as the figure argument.

Primer on Plotly Graphing Library

The Plotly Graphing Library,
known as the package package plotly, generates “figures”.
These are used in dcc.Graph with e.g. dcc.Graph(figure=fig)
with fig a plotly figure.
To get started with plotly, learn how its documentation is organized:
1. Learn the architecture of the figure: https://plot.ly/python/creating-and-updating-figures/
2. Every chart type has a set of examples at a unique URL.
  Familiarize yourself with the structure of these pages. Google is your friend.
  For example “Plotly Python Histogram Charts” is documented at
  https://plot.ly/python/histogram
3. Plotly Express is the recommended high-level interface.
  Understand where it fits in by reading 1.
  Once you understand its structure, you can see all of the arguments in the
  “API Reference” page documented here: https://plot.ly/python-api-reference/plotly.express.html
4. Every aspect of a chart is configurable.
  Read through 1 to understand the low-level figure interface and how to
  modify the properties of a generated figure.
  Once you understand it, view all of the
  properties by visiting the “Figure Reference” page at https://plot.ly/python/reference.
5. If you can’t generate the graph easily with px, then learn the
  graph_objects structure by reading 1 and understanding
  the structure of the figure via https://plot.ly/python/reference.
Plotly supports 40-50 different chart types. Learn more by navigating
https://plot.ly/python/
In development, you can create figures by running Dash apps or
in other environments like Jupyter, your console, and more.
If you are using the interface outside of Dash, then calling
fig.show() will always display the graph (either in your browser
or inline directly in your environment). To see all of these rendering
environments, see https://plot.ly/python/renderers/.

Examples

Plotly Express in Dash

The fig object is passed directly into the figure property of dcc.Graph:


import dash_core_components as dcc
import plotly.express as px

df = px.data.iris() # iris is a pandas DataFrame
fig = px.scatter(df, x="sepal_width", y="sepal_length")

dcc.Graph(figure=fig)

Using the Low-Level Interface with `go.Figure`

Read through (1) above to learn more about the difference between px & go.Figure.

import dash_core_components as dcc
import plotly.graph_objs as go
fig = go.Figure(data=[go.Scatter(x=[1, 2, 3], y=[4, 1, 2])])
dcc.Graph(
        id='example-graph-2',
        figure=fig
    )

Using the Low-Level Interface with Dicts & Lists

Read through (1) above to learn more about the difference between px, go.Figure, and dicts & lists.

import dash_core_components as dcc
dcc.Graph(
        id='example-graph',
        figure={
            'data': [
                {'x': [1, 2, 3], 'y': [4, 1, 2], 'type': 'bar', 'name': 'SF'},
                {'x': [1, 2, 3], 'y': [2, 4, 5], 'type': 'bar', 'name': u'Montréal'},
            ],
            'layout': {
                'title': 'Dash Data Visualization'
            }
        }
    )

Interactive Graphing with Callbacks

The Interactive Visualizations tutorial explains how
to capture user interaction events with a dcc.Graph, and how to update the
figure property in callbacks.

Some advanced features are documented in community forum posts:

How to preserve the UI state (zoom level etc.) of a Graph when updating the Graph in a callback
https://community.plot.ly/t/preserving-ui-state-like-zoom-in-dcc-graph-with-uirevision/15793
Graph transitions for smooth transitions or animations on Graph updates
https://community.plot.ly/t/exploring-a-transitions-api-for-dcc-graph/15468

Graph Resizing and Responsiveness

There are quite a few options that you can take advantage of if
you want the size of your graph to be reactive.

The default plotly.js behavior dictates that the graph should
resize upon window resize. However, in some cases, you might want
to resize the graph based on the size of its parent container
instead. (You can set the size of the parent container with the
style.height and style.width properties.)

The responsive property of the dcc.Graph component allows you
to define your desired behavior. In short, it accepts as a value
True, False, or 'auto':

True forces the graph to be responsive to window and parent
resize, regardless of any other specifications in
figure.layout or config
False forces the graph to be non-responsive to window and
parent resize, regardless of any other specifications in
figure.layout or config
'auto' preserves the legacy behavior (size and resizability
are determined by values specified in figure.layout and
config.responsive)

How Resizing Works - Advanced

The properties of dcc.Graph that can control the size of the
graph (other than responsive) are:

figure.layout.height - explicitly sets the height
figure.layout.width - explicitly sets the width
figure.layout.autosize - if True, sets the height and width
of the graph to that of its parent container
config.responsive - if True, changes the height and width of
the graph upon window resize

The responsive property works in conjunction with the above
properties in the following way:

True: config.responsive and figure.layout.autosize are
overriden with True values, and figure.layout.height and
figure.layout.width are unset
False: config.responsive and figure.layout.autosize are
both overriden with False values
'auto': the resizability of the plot is determined the
same way as it used to be (i.e., with the four properties above)

Graph Properties

Access this documentation in your Python terminal with:
```python

help(dash_core_components.Graph)
```

id (string; optional): The ID of this component, used to identify dash components in callbacks. The ID needs to be unique across all of the components in an app.

animate (boolean; default False): Beta: If true, animate between updates using plotly.js’s animate function

animation_options (dict; default { frame: { redraw: false, }, transition: { duration: 750, ease: 'cubic-in-out', }, }): Beta: Object containing animation settings. Only applies if animate is true

clickData (dict; optional): Data from latest click event. Read-only.

clickAnnotationData (dict; optional): Data from latest click annotation event. Read-only.

clear_on_unhover (boolean; default False): If True, clear_on_unhover will clear the hoverData property when the user “unhovers” from a point. If False, then the hoverData property will be equal to the data from the last point that was hovered over.

className (string; optional): className of the parent div

config (dict; optional): Plotly.js config options. See https://plotly.com/javascript/configuration-options/ for more info. config has the following type: dict containing keys ‘staticPlot’, ‘plotlyServerURL’, ‘editable’, ‘edits’, ‘autosizable’, ‘responsive’, ‘queueLength’, ‘fillFrame’, ‘frameMargins’, ‘scrollZoom’, ‘doubleClick’, ‘doubleClickDelay’, ‘showTips’, ‘showAxisDragHandles’, ‘showAxisRangeEntryBoxes’, ‘showLink’, ‘sendData’, ‘linkText’, ‘displayModeBar’, ‘showSendToCloud’, ‘showEditInChartStudio’, ‘modeBarButtonsToRemove’, ‘modeBarButtonsToAdd’, ‘modeBarButtons’, ‘toImageButtonOptions’, ‘displaylogo’, ‘watermark’, ‘plotGlPixelRatio’, ‘topojsonURL’, ‘mapboxAccessToken’, ‘locale’, ‘locales’. Those keys have the following types:

staticPlot (boolean; optional): No interactivity, for export or image generation
plotlyServerURL (string; optional): Base URL for a Plotly cloud instance, if showSendToCloud is enabled
editable (boolean; optional): We can edit titles, move annotations, etc - sets all pieces of edits unless a separate edits config item overrides individual parts
edits (dict; optional): A set of editable properties. edits has the following type: dict containing keys ‘annotationPosition’, ‘annotationTail’, ‘annotationText’, ‘axisTitleText’, ‘colorbarPosition’, ‘colorbarTitleText’, ‘legendPosition’, ‘legendText’, ‘shapePosition’, ‘titleText’. Those keys have the following types: - annotationPosition (boolean; optional): The main anchor of the annotation, which is the text (if no arrow) or the arrow (which drags the whole thing leaving the arrow length & direction unchanged) - annotationTail (boolean; optional): Just for annotations with arrows, change the length and direction of the arrow - annotationText (boolean; optional) - axisTitleText (boolean; optional) - colorbarPosition (boolean; optional) - colorbarTitleText (boolean; optional) - legendPosition (boolean; optional) - legendText (boolean; optional): Edit the trace name fields from the legend - shapePosition (boolean; optional) - titleText (boolean; optional): The global layout.title
autosizable (boolean; optional): DO autosize once regardless of layout.autosize (use default width or height values otherwise)
responsive (boolean; optional): Whether to change layout size when the window size changes
queueLength (number; optional): Set the length of the undo/redo queue
fillFrame (boolean; optional): If we DO autosize, do we fill the container or the screen?
frameMargins (number; optional): If we DO autosize, set the frame margins in percents of plot size
scrollZoom (boolean; optional): Mousewheel or two-finger scroll zooms the plot
doubleClick (a value equal to: false, ‘reset’, ‘autosize’, ‘reset+autosize’; optional): Double click interaction (false, ‘reset’, ‘autosize’ or ‘reset+autosize’)
doubleClickDelay (number; optional): Delay for registering a double-click event in ms. The minimum value is 100 and the maximum value is 1000. By default this is 300.
showTips (boolean; optional): New users see some hints about interactivity
showAxisDragHandles (boolean; optional): Enable axis pan/zoom drag handles
showAxisRangeEntryBoxes (boolean; optional): Enable direct range entry at the pan/zoom drag points (drag handles must be enabled above)
showLink (boolean; optional): Link to open this plot in plotly
sendData (boolean; optional): If we show a link, does it contain data or just link to a plotly file?
linkText (string; optional): Text appearing in the sendData link
displayModeBar (a value equal to: true, false, ‘hover’; optional): Display the mode bar (true, false, or ‘hover’)
showSendToCloud (boolean; optional): Should we include a modebar button to send this data to a Plotly Cloud instance, linked by plotlyServerURL. By default this is false.
showEditInChartStudio (boolean; optional): Should we show a modebar button to send this data to a Plotly Chart Studio plot. If both this and showSendToCloud are selected, only showEditInChartStudio will be honored. By default this is false.
modeBarButtonsToRemove (list; optional): Remove mode bar button by name. All modebar button names at https://github.com/plotly/plotly.js/blob/master/src/components/modebar/buttons.js Common names include: sendDataToCloud; (2D) zoom2d, pan2d, select2d, lasso2d, zoomIn2d, zoomOut2d, autoScale2d, resetScale2d; (Cartesian) hoverClosestCartesian, hoverCompareCartesian; (3D) zoom3d, pan3d, orbitRotation, tableRotation, handleDrag3d, resetCameraDefault3d, resetCameraLastSave3d, hoverClosest3d; (Geo) zoomInGeo, zoomOutGeo, resetGeo, hoverClosestGeo; hoverClosestGl2d, hoverClosestPie, toggleHover, resetViews.
modeBarButtonsToAdd (list; optional): Add mode bar button using config objects
modeBarButtons (boolean | number | string | dict | list; optional): Fully custom mode bar buttons as nested array, where the outer arrays represents button groups, and the inner arrays have buttons config objects or names of default buttons
toImageButtonOptions (dict; optional): Modifications to how the toImage modebar button works. toImageButtonOptions has the following type: dict containing keys ‘format’, ‘filename’, ‘width’, ‘height’, ‘scale’. Those keys have the following types: - format (a value equal to: ‘jpeg’, ‘png’, ‘webp’, ‘svg’; optional): The file format to create - filename (string; optional): The name given to the downloaded file - width (number; optional): Width of the downloaded file, in px - height (number; optional): Height of the downloaded file, in px - scale (number; optional): Extra resolution to give the file after rendering it with the given width and height
displaylogo (boolean; optional): Add the plotly logo on the end of the mode bar
watermark (boolean; optional): Add the plotly logo even with no modebar
plotGlPixelRatio (number; optional): Increase the pixel ratio for Gl plot images
topojsonURL (string; optional): URL to topojson files used in geo charts
mapboxAccessToken (boolean | number | string | dict | list; optional): Mapbox access token (required to plot mapbox trace types) If using an Mapbox Atlas server, set this option to ‘’, so that plotly.js won’t attempt to authenticate to the public Mapbox server.
locale (string; optional): The locale to use. Locales may be provided with the plot (locales below) or by loading them on the page, see: https://github.com/plotly/plotly.js/blob/master/dist/README.md#to-include-localization
locales (dict; optional): Localization definitions, if you choose to provide them with the plot rather than registering them globally.

extendData (list | dict; optional): Data that should be appended to existing traces. Has the form [updateData, traceIndices, maxPoints], where updateData is an object containing the data to extend, traceIndices (optional) is an array of trace indices that should be extended, and maxPoints (optional) is either an integer defining the maximum number of points allowed or an object with key:value pairs matching updateData Reference the Plotly.extendTraces API for full usage: https://plotly.com/javascript/plotlyjs-function-reference/#plotlyextendtraces

figure (dict; default { data: [], layout: {}, frames: [], }): Plotly figure object. See schema: https://plotly.com/javascript/reference config is set separately by the config property. figure has the following type: dict containing keys ‘data’, ‘layout’, ‘frames’. Those keys have the following types:

data (list of dicts; optional)
layout (dict; optional)
frames (list of dicts; optional)

hoverData (dict; optional): Data from latest hover event. Read-only.

loading_state (dict; optional): Object that holds the loading state object coming from dash-renderer. loading_state has the following type: dict containing keys ‘is_loading’, ‘prop_name’, ‘component_name’. Those keys have the following types:

is_loading (boolean; optional): Determines if the component is loading or not
prop_name (string; optional): Holds which property is loading
component_name (string; optional): Holds the name of the component that is loading

prependData (list | dict; optional): Data that should be prepended to existing traces. Has the form [updateData, traceIndices, maxPoints], where updateData is an object containing the data to prepend, traceIndices (optional) is an array of trace indices that should be prepended, and maxPoints (optional) is either an integer defining the maximum number of points allowed or an object with key:value pairs matching updateData Reference the Plotly.prependTraces API for full usage: https://plotly.com/javascript/plotlyjs-function-reference/#plotlyprependtraces

responsive (a value equal to: true, false, ‘auto’; default 'auto'): If True, the Plotly.js plot will be fully responsive to window resize and parent element resize event. This is achieved by overriding config.responsive to True, figure.layout.autosize to True and unsetting figure.layout.height and figure.layout.width. If False, the Plotly.js plot not be responsive to window resize and parent element resize event. This is achieved by overriding config.responsive to False and figure.layout.autosize to False. If ‘auto’ (default), the Graph will determine if the Plotly.js plot can be made fully responsive (True) or not (False) based on the values in config.responsive, figure.layout.autosize, figure.layout.height, figure.layout.width. This is the legacy behavior of the Graph component. Needs to be combined with appropriate dimension / styling through the style prop to fully take effect.

relayoutData (dict; optional): Data from latest relayout event which occurs when the user zooms or pans on the plot or other layout-level edits. Has the form {<attr>: <value>} describing the changes made. Read-only.

restyleData (list; optional): Data from latest restyle event which occurs when the user toggles a legend item, changes parcoords selections, or other trace-level edits. Has the form [edits, indices], where edits is an object {<attr>: <value>} describing the changes made, and indices is an array of trace indices that were edited. Read-only.

selectedData (dict; optional): Data from latest select event. Read-only.

style (dict; optional): Generic style overrides on the plot div