This PR fixes an issue wherelayout.title.subtitle does not properly clear/remove from the chart whensubtitle object is not in place, orsubtitle.text set tonull, empty string, or whitespace-only values viaPlotly.relayout().

Problem

When users attempted to clear a subtitle using any of these methods:

Plotly.relayout(gd,{'title.subtitle.text':null});Plotly.relayout(gd,{'title.subtitle.text':''});Plotly.relayout(gd,{'title.subtitle.text':'   '});Plotly.relayout(gd,{'title.subtitle':undefined});

The subtitle would remain visible on the chart. The only workaround was to set it to transparent:

Plotly.relayout(gd,{'title.subtitle.text':'no text','title.subtitle.font.color':'transparent'});

Root Cause

Insrc/components/titles/index.js -Line 163: The conditionif(subtitleEnabled && subtitleElShouldExist) prevented D3's.exit().remove() from running when the subtitle needed to be cleared.

Additional changes

Line 84: Handle null/undefinedsubtitle.text
Lines 244 & 408: Add checks for empty D3 selections to prevent operations on selections with 0 elements

Notes

This follows the same D3 enter/exit pattern already used for the main title element (lines 147-157 in the same file).

cminn10 added2 commits

October 5, 2025 00:23

fix(layout-subtitle): fixlayout.title.subtitle does not properly c…

270613c

…lear/remove from the chart

Add draftlog forplotly#7571

2ddb7fa

gvwilson requested review fromcamdecoster andemilykl

October 7, 2025 13:16

gvwilson added community

community contribution

considered for next cycle

fixfixes something broken labels

Oct 7, 2025

Copy link

Contributor

gvwilson commentedOct 7, 2025

Thanks for the fix@cminn10 - we'll see if we can find a reviewer for the next release.

Copy link

Contributor

emilykl commentedOct 7, 2025

This bug is almost definitely my fault 🙂 Thank you@cminn10 for the very precise fix!

@cminn10 This looks great. One nit -- this fix doesn't actually cause the subtitle to be removed when settingPlotly.relayout(gd, {'title.subtitle': undefined}); (orPlotly.relayout(gd, {'title.subtitle.text': undefined});)but that's fine -- a general property of Plotly.js is that setting a value toundefined is treated as a noop (title behaves the same way). SettingPlotly.relayout(gd, {'title.subtitle.text': {}}); DOES work thanks to this PR.

I'd like to add a Jasmine test to prevent a regression. Can you add this test totest/jasmine/tests/titles_test.js?

describe('Subtitle clearing via relayout', function() {    'use strict';    var data = [{ x: [1, 2, 3], y: [1, 2, 3] }];    var gd;    beforeEach(function() {        gd = createGraphDiv();    });    afterEach(destroyGraphDiv);    it('should properly clear subtitle when set to null', function(done) {        Plotly.newPlot(gd, data, {            title: {                text: 'Main Title',                subtitle: { text: 'Subtitle Text' }            }        })            .then(function() {                var subtitleSel = d3Select('.gtitle-subtitle');                expect(subtitleSel.empty()).toBe(false, 'Subtitle should exist initially');                expect(subtitleSel.text()).toBe('Subtitle Text');                return Plotly.relayout(gd, { 'title.subtitle.text': null });            })            .then(function() {                var subtitleSel = d3Select('.gtitle-subtitle');                expect(subtitleSel.empty()).toBe(true, 'Subtitle should be removed when set to null');            })            .then(done, done.fail);    });    it('should properly clear subtitle when set to empty string', function(done) {        Plotly.newPlot(gd, data, {            title: {                text: 'Main Title',                subtitle: { text: 'Subtitle Text' }            }        })            .then(function() {                var subtitleSel = d3Select('.gtitle-subtitle');                expect(subtitleSel.empty()).toBe(false, 'Subtitle should exist initially');                return Plotly.relayout(gd, { 'title.subtitle.text': '' });            })            .then(function() {                var subtitleSel = d3Select('.gtitle-subtitle');                expect(subtitleSel.empty()).toBe(true, 'Subtitle should be removed when set to empty string');            })            .then(done, done.fail);    });    it('should properly clear subtitle when set to whitespace', function(done) {        Plotly.newPlot(gd, data, {            title: {                text: 'Main Title',                subtitle: { text: 'Subtitle Text' }            }        })            .then(function() {                var subtitleSel = d3Select('.gtitle-subtitle');                expect(subtitleSel.empty()).toBe(false, 'Subtitle should exist initially');                return Plotly.relayout(gd, { 'title.subtitle.text': '   ' });            })            .then(function() {                var subtitleSel = d3Select('.gtitle-subtitle');                expect(subtitleSel.empty()).toBe(true, 'Subtitle should be removed when set to whitespace');            })            .then(done, done.fail);    });});