Plotly v3 - title attribute changes

- remove deprecated titlefont, titleside, etc.
- it is no longer valid to pass a plain string as "title"

plotly/plotly.js#7212

Author: ianroberts

types/plotly.js/index.d.ts

@@ -409,26 +409,23 @@ export function animate(
 // Layout
 export interface Layout {
     colorway: string[];
-    title:
-        | string
-        | Partial<{
-            text: string;
-            font: Partial<Font>;
-            xref: "container" | "paper";
-            yref: "container" | "paper";
-            x: number;
-            y: number;
-            xanchor: "auto" | "left" | "center" | "right";
-            yanchor: "auto" | "top" | "middle" | "bottom";
-            pad: Partial<Padding>;
-            subtitle:
-                | string
-                | Partial<{
-                    text: string;
-                    font: Partial<Font>;
-                }>;
-        }>;
-    titlefont: Partial<Font>;
+    title: Partial<{
+        text: string;
+        font: Partial<Font>;
+        xref: "container" | "paper";
+        yref: "container" | "paper";
+        x: number;
+        y: number;
+        xanchor: "auto" | "left" | "center" | "right";
+        yanchor: "auto" | "top" | "middle" | "bottom";
+        pad: Partial<Padding>;
+        subtitle:
+            | string
+            | Partial<{
+                text: string;
+                font: Partial<Font>;
+            }>;
+    }>;
     autosize: boolean;
     showlegend: boolean;
     paper_bgcolor: Color;
@@ -460,6 +457,12 @@ export interface Layout {
     hoverdistance: number;
     hoverlabel: Partial<HoverLabel>;
     calendar: Calendar;
+
+    // these are just the most common nested property updates that you might
+    // want to pass to Plotly.relayout - *any* dotted property path through the
+    // normal nested structure is valid here, and enumerating them all including
+    // all possible [n] array indices would be infeasible (if it weren't for the
+    // array indices, the pure a.b.c bit might be doable with conditional types)
     "xaxis.range": [Datum, Datum];
     "xaxis.range[0]": Datum;
     "xaxis.range[1]": Datum;
@@ -470,8 +473,8 @@ export interface Layout {
     "xaxis.type": AxisType;
     "xaxis.autorange": boolean;
     "yaxis.autorange": boolean;
-    "xaxis.title": string;
-    "yaxis.title": string;
+    "xaxis.title": Partial<DataTitle>;
+    "yaxis.title": Partial<DataTitle>;
     ternary: {}; // TODO
     geo: {}; // TODO
     mapbox: Partial<Mapbox>;
@@ -664,12 +667,7 @@ export interface Axis {
      * Individual pieces can override this.
      */
     color: Color;
-    title: string | Partial<DataTitle>;
-    /**
-     * Former `titlefont` is now the sub-attribute `font` of `title`.
-     * To customize title font properties, please use `title.font` now.
-     */
-    titlefont: Partial<Font>;
+    title: Partial<DataTitle>;
     type: AxisType;
     autorange: true | false | "reversed" | "min reversed" | "max reversed" | "min" | "max";
     autorangeoptions: Partial<AutoRangeOptions>;
@@ -1591,6 +1589,12 @@ export interface Transform {
     order: "ascending" | "descending";
 }
 
+export interface ColorBarTitle {
+    text: string;
+    font: Partial<Font>;
+    side: "right" | "top" | "bottom";
+}
+
 export interface ColorBar {
     thicknessmode: "fraction" | "pixels";
     thickness: number;
@@ -1630,9 +1634,7 @@ export interface ColorBar {
     exponentformat: "none" | "e" | "E" | "power" | "SI" | "B";
     showexponent: "all" | "first" | "last" | "none";
     minexponent: number;
-    title: string;
-    titlefont: Font;
-    titleside: "right" | "top" | "bottom";
+    title: Partial<ColorBarTitle>;
     tickvalssrc: any;
     ticktextsrc: any;
 }

types/plotly.js/test/core-tests.ts

@@ -36,13 +36,17 @@ const layout = {
         subtitle: "Annual sales growth between 1999 and 2002",
     },
     xaxis: {
-        title: "Year",
+        title: {
+            text: "Year",
+        },
         showgrid: false,
         zeroline: false,
         tickangle,
     },
     yaxis: {
-        title: "Percent",
+        title: {
+            text: "Percent",
+        },
         showline: false,
     },
     uirevision: "true",
@@ -71,7 +75,7 @@ const layout = {
         opacity: 0.6,
         meanline: { visible: true },
     } as ViolinData;
-    Plotly.newPlot(graphDiv, [violinTrace], { title: "Sales growth" });
+    Plotly.newPlot(graphDiv, [violinTrace], { title: { text: "Sales growth" } });
 
     const candlestickTrace: Partial<CandlestickData> = {
         x: [
@@ -247,7 +251,7 @@ const layout = {
         type: "candlestick",
         xaxis: "x",
     };
-    Plotly.newPlot(graphDiv, [candlestickTrace], { title: "Stock price" });
+    Plotly.newPlot(graphDiv, [candlestickTrace], { title: { text: "Stock price" } });
 })();
 (() => {
     const data: Array<Partial<SankeyData>> = [
@@ -272,7 +276,9 @@ const layout = {
         },
     ];
     const layout = {
-        title: "Basic Sankey",
+        title: {
+            text: "Basic Sankey",
+        },
         font: {
             size: 10,
         },
@@ -289,7 +295,7 @@ const layout = {
             type: "scatter",
         } as ScatterData,
     ];
-    const layout2 = { title: "Revenue" };
+    const layout2 = { title: { text: "Revenue" } };
     Plotly.newPlot(graphDiv, data2, layout2);
 })();
 
@@ -424,7 +430,9 @@ const layout = {
     ];
 
     const layout = {
-        title: "Global Emissions 1990-2011",
+        title: {
+            text: "Global Emissions 1990-2011",
+        },
         annotations: [
             {
                 font: {
@@ -612,7 +620,9 @@ const layout = {
 // update only values within nested objects
 (() => {
     const update: Partial<Layout> = {
-        title: "some new title", // updates the title
+        title: { // updates the title
+            text: "some new title",
+        },
         "xaxis.range": [0, 5], // updates the xaxis range
         "yaxis.range[1]": 15, // updates the end of the yaxis range
     };
@@ -624,7 +634,9 @@ const layout = {
         marker: { color: "red" },
     };
     const layout_update = {
-        title: "some new title", // updates the title
+        title: { // updates the title
+            text: "some new title",
+        },
     };
     Plotly.update(graphDiv, data_update, layout_update);
 })();
@@ -638,7 +650,9 @@ const layout = {
         type: "bar",
     };
     const layout_update: Partial<Layout> = {
-        title: "some new title", // updates the title
+        title: { // updates the title
+            text: "some new title",
+        },
         barmode: "stack",
         barnorm: "fraction",
         bargap: 0,

types/plotly.js/test/index-tests.ts

@@ -128,15 +128,21 @@ const graphDiv = "#test";
     } as PlotData;
     const data = [trace1, trace2, trace3];
     const layout = {
-        title: "Gapminder",
+        title: {
+            text: "Gapminder",
+        },
         xaxis: {
-            title: "Life Expectancy",
+            title: {
+                text: "Life Expectancy",
+            },
             domain: [0, 0.85],
             showgrid: false,
             zeroline: false,
         },
         yaxis: {
-            title: "GDP per Cap",
+            title: {
+                text: "GDP per Cap",
+            },
             showline: false,
             domain: [0, 0.85],
             showgrid: false,
@@ -165,7 +171,7 @@ const graphDiv = "#test";
             type: "scatter",
         } as PlotData,
     ];
-    const layout2 = { title: "Revenue" };
+    const layout2 = { title: { text: "Revenue" } };
     Plotly.newPlot(graphDiv, data2, layout2);
 })();
 (() => {
@@ -313,7 +319,13 @@ const graphDiv = "#test";
         yanchor: "top",
     };
 
-    const layout: Partial<Layout> = { showlegend: true, title: "January 2013 Sales Report", template, modebar, legend };
+    const layout: Partial<Layout> = {
+        showlegend: true,
+        title: { text: "January 2013 Sales Report" },
+        template,
+        modebar,
+        legend,
+    };
     const config: Partial<Config> = {
         modeBarButtons: [
             [
@@ -414,7 +426,9 @@ const graphDiv = "#test";
         },
     ];
     const layout: Partial<Layout> = {
-        title: "Grouped Box Plot",
+        title: {
+            text: "Grouped Box Plot",
+        },
         boxmode: "overlay",
     };
 
@@ -425,7 +439,9 @@ const graphDiv = "#test";
     const data: Array<Partial<PlotData>> = [
         {
             colorbar: {
-                title: "Test",
+                title: {
+                    text: "Test",
+                },
             },
             locationmode: "ISO-3",
             locations: ["USA", "NLD"],
@@ -436,7 +452,9 @@ const graphDiv = "#test";
     ];
     const layout: Partial<Layout> = {
         showlegend: true,
-        title: "World Map",
+        title: {
+            text: "World Map",
+        },
         geo: {
             projection: { type: "Mercator" },
             showcoastlines: true,
@@ -577,7 +595,9 @@ const graphDiv = "#test";
 // update only values within nested objects
 (() => {
     const update = {
-        title: "some new title", // updates the title
+        title: { // updates the title
+            text: "some new title",
+        },
         "xaxis.range": [0, 5], // updates the xaxis range
         "yaxis.range[1]": 15, // updates the end of the yaxis range
     } as Layout;
@@ -589,7 +609,9 @@ const graphDiv = "#test";
         marker: { color: "red" },
     };
     const layout_update = {
-        title: "some new title", // updates the title
+        title: { // updates the title
+            text: "some new title",
+        },
     };
     Plotly.update(graphDiv, data_update, layout_update);
 })();
@@ -620,7 +642,9 @@ const graphDiv = "#test";
         marker: { color: "red" },
     };
     const layout_update = {
-        title: "some new title", // updates the title
+        title: { // updates the title
+            text: "some new title",
+        },
     };
     Plotly.update(graphDiv, data_update, layout_update);
 })();