Title: [FEATURE]: pixel-based spacing for subplot domains (so titles can't overlap the plot above) · Issue #7835 · plotly/plotly.js · GitHub
Open Graph Title: [FEATURE]: pixel-based spacing for subplot domains (so titles can't overlap the plot above) · Issue #7835 · plotly/plotly.js
X Title: [FEATURE]: pixel-based spacing for subplot domains (so titles can't overlap the plot above) · Issue #7835 · plotly/plotly.js
Description: Description Over in plotly.py there's a long-standing papercut with make_subplots: if you set a small vertical_spacing and also pass subplot_titles, the titles overlap the subplot above them (plotly/plotly.py#5606). The underlying limita...
Open Graph Description: Description Over in plotly.py there's a long-standing papercut with make_subplots: if you set a small vertical_spacing and also pass subplot_titles, the titles overlap the subplot above them (plotl...
X Description: Description Over in plotly.py there's a long-standing papercut with make_subplots: if you set a small vertical_spacing and also pass subplot_titles, the titles overlap the subplot above them (p...
Opengraph URL: https://github.com/plotly/plotly.js/issues/7835
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[FEATURE]: pixel-based spacing for subplot domains (so titles can't overlap the plot above)","articleBody":"### Description\n\nOver in plotly.py there's a long-standing papercut with `make_subplots`: if you set a small `vertical_spacing` and also pass `subplot_titles`, the titles overlap the subplot above them (plotly/plotly.py#5606).\n\nThe underlying limitation looks like it's in plotly.js. Subplot titles are paper-referenced annotations pinned to the top of each subplot's domain. Their height is a **pixel** quantity (it scales with font size), but `vertical_spacing` is expressed as a **plot fraction** and ends up as the gap between adjacent `domain` bands. So whether a title fits depends on the rendered pixel height of the plot area — which isn't known until draw time, and changes when the containing div is resized.\n\nThat's why this can't be solved cleanly on the plotly.py side: when `make_subplots` builds the figure it doesn't know the final height (it's often set later, or left responsive), so any fraction it picks for the gap is wrong at some height. The reporter flagged this directly in the original issue:\n\n> \"axis.domain only supports units of plot fraction, not sure if there is a way to shift it by a certain number of pixels.\"\n\nAnd @emilykl's steer on the plotly.py issue was:\n\n> \"in order to support this fix, Plotly.js will need to be modified to support pixel offsets for domain, or something along those lines... please open an issue in Plotly.js linking to this issue and proposing a change to the API.\"\n\nSo this is that issue. Since the final subplot layout is resolved at render time, this looks like the right layer to sort it out. There are two shapes this could take — I've laid out both below.\n\n**Approach A — let domain spacing carry a pixel component (resolved at draw time)**\n\nAllow the gap between subplot domains (or the domain bounds themselves) to be specified partly in pixels, resolved against the real plot-area size during layout, the same way `margin` already is. Conceptually it's `domain = fraction ± pixels`, with the pixel part applied when the actual height is known. This is general-purpose — anyone who needs a fixed-pixel gutter between subplots benefits, not just titled ones — and it's the most direct reading of \"pixel offsets for domain\".\n\n**Approach B — make subplot titles reserve their own space via the existing automargin machinery**\n\nInstead of a new public attribute, let subplot titles participate in the draw-time margin/automargin pass so each title reserves a pixel-sized band and pushes the neighbouring domain down at render time. No new config for users; the overlap just stops happening. The trade-off is that it shifts existing baselines automatically and is specific to titles rather than a general spacing primitive.\n\nApproach A is more general-purpose; Approach B has a smaller public API surface and reuses machinery that already exists. I'm not trying to prescribe an API here — the goal is to work out whether pixel-aware domain spacing, title-aware layout reservation, or some other render-time mechanism fits the existing layout model best. Happy with whichever direction the team prefers.\n\n### Why should this feature be added?\n\nThis is a common configuration (compact stacked subplots with titles — dashboards, multi-metric time series) and today it produces visibly broken output with no real workaround from the Python API. plotly.py can't fix it without this, because the decision depends on the rendered pixel height. A pixel-aware spacing primitive would close plotly/plotly.py#5606 and, more broadly, give anyone a way to reserve fixed-pixel space between subplots regardless of figure height.\n\n### Mocks/Designs\n\nMinimal repro (Python, but the overlap is produced by plotly.js at render time):\n\n```python\nfrom plotly.subplots import make_subplots\nimport plotly.graph_objects as go\nimport random\n\nfig = make_subplots(\n rows=6, cols=1,\n shared_xaxes=True,\n vertical_spacing=0.02,\n row_heights=[0.35, 0.13, 0.13, 0.13, 0.13, 0.13],\n subplot_titles=['Heart Rate Variability', 'Walking', 'Cycling', 'Hiking', 'Other', 'Pilates'],\n)\nfor i in range(6):\n fig.add_trace(\n go.Scatter(x=[0, 1, 2], y=[random.randint(0, 10) for _ in range(3)]),\n row=i + 1, col=1,\n )\nfig.show()\n```\n\nEach title (a paper annotation at the top of its domain) grows upward into the small fraction gap above it. When that gap is small relative to the rendered pixel height of the title, the title overlaps the subplot above — and because the gap is a fraction while the title height is fixed pixels, whether it overlaps depends on the figure's rendered height. Screenshot of the overlap is on the linked issue: plotly/plotly.py#5606.\n\nSketch of the Approach A API (illustrative only):\n\n```\n// gap between subplot domains, resolved at draw time\ndomain: { ..., pad: 30 } // 30px reserved, independent of figure height\n```\n\n### Notes\n\nplotly.js already does pixel-aware, draw-time layout in two places, which is why I think either approach is feasible without new machinery:\n\n- **`automargin`** grows the figure margins for long tick labels at render time, once pixel sizes are known.\n- **annotation `yshift` / `xshift`** are pixel offsets that already coexist with fractional/paper positioning.\n\nApproach B reuses the first directly; Approach A is the same idea generalised to domain spacing.\n\nLinked issue: plotly/plotly.py#5606. Happy to take a crack at the implementation once there's agreement on which direction to go.\n","author":{"url":"https://github.com/SharadhNaidu","@type":"Person","name":"SharadhNaidu"},"datePublished":"2026-06-10T18:28:59Z","url":"https://github.com/plotly/plotly.js/issues/7835"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:2ada434a-a050-9107-da16-d315042b03b0 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B1EA:ADA9D:3437EFC:42FEE70:6B01D453 |
| html-safe-nonce | 06a8c7f6c8e1becbf72f96ac1fd909562affddc80acb41e0eccf6e9bf1b44106 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCMUVBOkFEQTlEOjM0MzdFRkM6NDJGRUU3MDo2QjAxRDQ1MyIsInZpc2l0b3JfaWQiOiI4NDE1Nzg0ODE5Njc3NTgyNDE5IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 661c022b62ef3bbd9905554341f14b0e7b6b858668c4e251c50beda1259f6f7f |
| hovercard-subject-tag | issue:4633929277 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/plotly/plotly.js/7835/issue_layout |
| twitter:image | https://opengraph.githubassets.com/45f224ec84d8f784a887fd310bb0c33e80fb010a291e371bbf97a61303271f17/plotly/plotly.js/issues/7835 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/45f224ec84d8f784a887fd310bb0c33e80fb010a291e371bbf97a61303271f17/plotly/plotly.js/issues/7835 |
| og:image:alt | Description Over in plotly.py there's a long-standing papercut with make_subplots: if you set a small vertical_spacing and also pass subplot_titles, the titles overlap the subplot above them (plotl... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | SharadhNaidu |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/plotly/plotly.js git https://github.com/plotly/plotly.js.git |
| octolytics-dimension-user_id | 5997976 |
| octolytics-dimension-user_login | plotly |
| octolytics-dimension-repository_id | 45646037 |
| octolytics-dimension-repository_nwo | plotly/plotly.js |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 45646037 |
| octolytics-dimension-repository_network_root_nwo | plotly/plotly.js |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width