# dcc_graph

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 `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://plotly.com/julia/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 "Histograms in Julia" is documented at https://plotly.com/julia/histograms

  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://plotly.com/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://plotly.com/julia/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 viahttps://plotly.com/julia/reference

- Plotly supports 40-50 different chart types. Learn more by navigating https://plotly.com/julia/.
- 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://plotly.com/julia/renderers/

## Examples

### Plotly Express in Dash

The `fig` object is passed directly into the `figure` property of `dcc_graph`:

    using DataFrames, CSV, PlotlyJS
    using Dash

    iris = dataset(DataFrame, "iris")
    fig = p1 = plot(
        iris, x=:sepal_length, y=:sepal_width, color=:species,
        mode="markers", marker_size=8
    )

    app = dash()

    app.layout = html_div() do
        html_h4("Iris Sepal Length vs Sepal Width"),
        dcc_graph(
            id="example-graph-3",
            figure=fig,
        )
    end

    run_server(app, "0.0.0.0", debug=true)

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

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

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

> This example has not been ported to Julia yet - showing the Python version instead.

> Visit the old docs site for Julia at: https://community.plotly.com/c/dash/julia/20

    from dash import dcc
    import plotly.graph_objs as go

    fig = go.Figure(data=[go.Scatter(x=[1, 2, 3], y=[4, 1, 2])])

    dcc.Graph(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`.

    using Dash, PlotlyJS

    app = dash()

    app.layout = dcc_graph(
      id="example-graph",
      figure=Plot([
          bar(x=1:3, y=[4, 1, 2], name="SF"),
          bar(x=1:3, y=[2, 4, 5], name="Montréal"),
      ], Layout(title="Dash Data Visualization")
      )
    )

    run_server(app, "0.0.0.0", debug=true)

## Interactive Graphing with Callbacks

Interactive Visualizations in the Dash Fundamentals 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

Sign up for Dash Club → Two free cheat sheets plus updates from Chris Parmer and Adam Schroeder delivered to your inbox every two months. Includes tips and tricks, community apps, and deep dives into the Dash architecture. Join now.

## Controlling the Plotly.js Version Used by dcc_graph

The `dcc_graph` component leverages the Plotly.js library to render visualizations.

You can override the Plotly.js version by placing a Plotly.js bundle in the `assets` directory.

This technique can be used to:

- take advantage of new features in a version of Plotly.js that is more recent than the one that is included in the currently installed version of Dash or Dash Design Kit.
- take advantage of more desirable behavior of a version of Plotly.js that is less recent than the one that is included in the currently installed version of Dash or Dash Design Kit. We strive to make Plotly.js releases completely backwards-compatible, so you shouldn't have to do this very often.
- use a Plotly-distributed Plotly.js partial bundle or a custom-built Plotly.js bundle which only includes the subset of Plotly.js features that your Dash app uses. Partial bundles are smaller than the full Plotly.js bundles that come with the `Graph` component and can therefore improve your app's loading time.

## LaTeX

`dcc_graph` supports rendering LaTeX on titles, labels, and annotations. It uses MathJax version 3.2 and can be enabled by setting `mathjax=True` on the component. Put content to be rendered with MathJax between `$` delimiters. If you need a literal `$`, use the HTML entity `&#36;`. To include text within MathJax delimiters, use `\text{<your_text_goes_here>}`. In the following example `(solar radius)` is included as text on the `yaxis_title`.

> This example has not been ported to Julia yet - showing the Python version instead.

> Visit the old docs site for Julia at: https://community.plotly.com/c/dash/julia/20

    from dash import Dash, dcc, html
    import plotly.express as px

    fig = px.line(x=[1, 2, 3, 4], y=[1, 4, 9, 16], title=r'$\alpha_{1c} = 352 \pm 11 \text{ km s}^{-1}$')
    fig.update_layout(
        xaxis_title=r'$\sqrt{(n_\text{c}(t|{T_\text{early}}))}$',
        yaxis_title=r'$d, r \text{ (solar radius)}$'
    )

    app = Dash()

    app.layout = html.Div([

        dcc.Markdown('''
        ## LaTeX in a Markdown component:

        This example uses the block delimiter:
        $$
        \\frac{1}{(\\sqrt{\\phi \\sqrt{5}}-\\phi) e^{\\frac25 \\pi}} =
        1+\\frac{e^{-2\\pi}} {1+\\frac{e^{-4\\pi}} {1+\\frac{e^{-6\\pi}}
        {1+\\frac{e^{-8\\pi}} {1+\\ldots} } } }
        $$

        This example uses the inline delimiter:
        $E^2=m^2c^4+p^2c^2$

        ## LaTeX in a Graph component:

        ''', mathjax=True),

        dcc.Graph(mathjax=True, figure=fig)]
    )

    if __name__ == '__main__':
        app.run(debug=True)

## LaTeX in a Markdown component:

This example uses the block delimiter:

1(ϕ 5−ϕ)e 2 5 π=1+e−2 π 1+e−4 π 1+e−6 π 1+e−8 π 1+…

This example uses the inline delimiter:
E 2=m 2 c 4+p 2 c 2

## LaTeX in a Graph component:

> Rendering LaTeX is not currently supported on `hovertext`, `texttemplate`, `ticktext`, `text` on bar chart bars, or `labels` when displayed on pie charts. If you or your company would like to sponsor improvements to LaTeX rendering in Dash, get in touch with our advanced development team.

For an introduction to LaTeX math, see LaTeX/Mathematics.

## 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 overridden with `true` values, and `figure.layout.height` and `figure.layout.width` are unset
- `false`: `config.responsive` and `figure.layout.autosize` are both overridden 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

> Our recommended IDE for writing Dash apps is Dash Enterprise's Data Science Workspaces, which has typeahead support for Dash Component Properties. Find out if your company is using Dash Enterprise.

`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.

`responsive` (a value equal to: true, false or '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.

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

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

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

`clear_on_unhover` (Bool; 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.

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

`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 string>: <value>}` describing the changes made. Read-only.

`extendData` (Array | 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.

`prependData` (Array | 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.

`restyleData` (Array; 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 string>: <value>}` describing the changes made, and `indices` is an array of trace indices that were edited. Read-only.

`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` is a Dict with keys:

- `data` (Array of Dicts; optional)

- `frames` (Array of Dicts; optional)

- `layout` (Dict; optional)

`style` (Dict; optional): Generic style overrides on the plot div.

`className` (String; optional): className of the parent div.

`mathjax` (Bool; default `false`): If true, loads mathjax v3 (tex-svg) into the page and use it in the graph.

`animate` (Bool; 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`.

`config` (Dict; optional): Plotly.js config options. See https://plotly.com/javascript/configuration-options/ for more info.

`config` is a Dict with keys:

- `autosizable` (Bool; optional): DO autosize once regardless of layout.autosize (use default width or height values otherwise).

- `displayModeBar` (a value equal to: true, false or 'hover'; optional): Display the mode bar (true, false, or 'hover').

- `displaylogo` (Bool; optional): Add the plotly logo on the end of the mode bar.

- `doubleClick` (a value equal to: false, 'reset', 'autosize' or 'reset+autosize'; optional): Double click interaction (false, 'reset', 'autosize' or 'reset+autosize').

- `doubleClickDelay` (Real; 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.

- `editSelection` (Bool; optional): Enables moving selections.

- `editable` (Bool; 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` is a Dict with keys:

  - `annotationPosition` (Bool; 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` (Bool; optional): Just for annotations with arrows, change the length and direction of the arrow.

  - `annotationText` (Bool; optional)

  - `axisTitleText` (Bool; optional)

  - `colorbarPosition` (Bool; optional)

  - `colorbarTitleText` (Bool; optional)

  - `legendPosition` (Bool; optional)

  - `legendText` (Bool; optional): Edit the trace name fields from the legend.

  - `shapePosition` (Bool; optional)

  - `titleText` (Bool; optional): The global `layout.title`.

- `fillFrame` (Bool; optional): If we DO autosize, do we fill the container or the screen?.

- `frameMargins` (Real; optional): If we DO autosize, set the frame margins in percents of plot size.

- `linkText` (String; optional): Text appearing in the sendData link.

- `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.

- `mapboxAccessToken` (Bool | Real | String | Array | Dict; 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.

- `modeBarButtons` (Bool | Real | String | Array | Dict; 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.

- `modeBarButtonsToAdd` (Array; optional): Add mode bar button using config objects.

- `modeBarButtonsToRemove` (Array; 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.

- `plotGlPixelRatio` (Real; optional): Increase the pixel ratio for Gl plot images.

- `plotlyServerURL` (String; optional): Base URL for a Plotly cloud instance, if `showSendToCloud` is enabled.

- `queueLength` (Real; optional): Set the length of the undo/redo queue.

- `responsive` (Bool; optional): Whether to change layout size when the window size changes.

- `scrollZoom` (Bool; optional): Mousewheel or two-finger scroll zooms the plot.

- `sendData` (Bool; optional): If we show a link, does it contain data or just link to a plotly file?.

- `showAxisDragHandles` (Bool; optional): Enable axis pan/zoom drag handles.

- `showAxisRangeEntryBoxes` (Bool; optional): Enable direct range entry at the pan/zoom drag points (drag handles must be enabled above).

- `showEditInChartStudio` (Bool; 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.

- `showLink` (Bool; optional): Link to open this plot in plotly.

- `showSendToCloud` (Bool; optional): Should we include a modebar button to send this data to a Plotly Cloud instance, linked by `plotlyServerURL`. By default this is false.

- `showTips` (Bool; optional): New users see some hints about interactivity.

- `staticPlot` (Bool; optional): No interactivity, for export or image generation.

- `toImageButtonOptions` (Dict; optional): Modifications to how the toImage modebar button works.

  `toImageButtonOptions` is a Dict with keys:

  - `filename` (String; optional): The name given to the downloaded file.

  - `format` (a value equal to: 'jpeg', 'png', 'webp' or 'svg'; optional): The file format to create.

  - `height` (Real; optional): Height of the downloaded file, in px.

  - `scale` (Real; optional): Extra resolution to give the file after rendering it with the given width and height.

  - `width` (Real; optional): Width of the downloaded file, in px.

- `topojsonURL` (String; optional): URL to topojson files used in geo charts.

- `watermark` (Bool; optional): Add the plotly logo even with no modebar.

`loading_state` (Dict; optional): Object that holds the loading state object coming from dash-renderer.

`loading_state` is a Dict with keys:

- `component_name` (String; optional): Holds the name of the component that is loading.

- `is_loading` (Bool; optional): Determines if the component is loading or not.

- `prop_name` (String; optional): Holds which property is loading.