Plotly 4.x to 5.x migration: Figure dict schema and layout template compatibility

Answer

To keep the modebar and layout template rendering identical between Plotly 4.x and 5.x, explicitly set figure.layout.template (e.g., 'plotly' or 'plotly_white') and figure.config.displayModeBar to true (with any desired button removals) before the figure is passed to dcc.Graph. This locks the defaults that otherwise shift in 5.x.

Why the change matters (likely explanation)

In Plotly 4.x the layout template was optional and visual defaults lived directly in the layout keys (font, colorway, hovermode, etc.). Plotly 5.x makes 'plotly' the implicit default template and moves those defaults into the template system. The modebar also changed its default orientation and button set. If a figure relies on the old implicit defaults, the resolved layout after template merging can differ, causing visible shifts or missing UI elements.

Confirmed facts from Plotly 5.x behavior

Plotly 5.x validates layout.template and layout.template.data more strictly. Setting template to a known value prevents the library from falling back to its internal defaults. The modebar defaults in 5.x are displayModeBar: true with a vertical orientation; specifying config explicitly freezes the UI across versions. The plotly.io.validate function (or to_json(validate=True)) will raise on deprecated layout keys that should reside inside a template.

Steps to normalize figure dicts

1. Ensure every figure dict has a template:

   if 'template' not in fig['layout']:
       fig['layout']['template'] = 'plotly'  # or 'plotly_white'
   

2. Freeze modebar settings:

   if 'config' not in fig:
       fig['config'] = {'displayModeBar': True, 'displaylogo': False}
   # optionally add button removals
   fig['config'].setdefault('modeBarButtonsToRemove', ['pan2d', 'lasso2d'])
   

3. Move any inline layout overrides (font, colorway, hovermode, etc.) into a custom template object and assign it to layout.template, then strip those keys from the layout root. This mirrors how 5.x merges template.layout over the base layout.

4. Validate the normalized figure before returning it from a Dash callback:

   import plotly.io as pio
   pio.to_json(fig, validate=True)  # raises if schema drift remains
   

5. In a zero‑downtime deployment, wrap the figure‑generation function with the normalizer so both 4.x and 5.x codepaths produce the same dict.