Upgrade MathJax support from v2/v3 to v3/v4 by emilykl · Pull Request #7898 · plotly/plotly.js

emilykl · 2026-07-10T12:17:52Z

Update plotly.js to be compatible with MathJax v4, and drop support for MathJax v2.

Due to some logic improvements, this should also make MathJax rendering faster.

Modify svg_text_utils.js to use MathJax v3/v4 syntax to render math symbols
- MathJax v3 and v4 use the same syntax, so we can get rid of the if/else cases we used to handle v2 and v3
- MathJax v4 uses asynchronous rendering calls only, so a small amount of refactoring is required to handle the asynchronous renders
Improve performance by not calling MathJax.startup.defaultReady() on every individual render. This was very slow and also not recommended usage of the MathJax API
- Instead, create a secondary MathJax document upfront that we can use for our purposes, without affecting the page's main MathJax document, and call MathDocument.convert(tex) rather than MathJax.typeset(tex)
- This also means we no longer have to reset the config after rendering, since the config is applied only to our internal MathJax document
- This approach does involve three places where we reference functions/objects in the MathJax._. namespace. While not officially documented, the pattern is used in several places (one, two, three) in the MathJax documentation for advanced configuration
  - The context is that the MathJax API is really intended for rendering entire documents/pages in one shot, so it doesn't directly expose functions for rendering individual expressions one-at-a-time. I feel fine about this workaround though, given that it works in both v3 and v4
- As a nice side effect, this change should make MathJax rendering in plotly much faster
Update image baselines
- There are visible differences, but no regressions; all the changes are minor typsetting differences in character spacing or line height, which makes sense for a new MathJax version
Update all testing infrastructure to use MathJax v3 and v4 rather than v2 and v3.
- NOTE: I've done this by changing all references to v2 to v4. This means that v4 is now the "default" in the CI, unless v3 is explicitly specified

Steps for testing

Check out this branch
Run the test dashboard (npm start) which uses MathJax 4
Verify that every mock with mathjax in the name (and the other baselines changed here) looks OK and matches the new baselines on this branch
- Note: The mathjax mock itself contains several strings of TeX which don't render due to syntax errors; this is not new, and it's deliberate, to test the fallback behavior
Visit the MathJax 3 test dashboard (http://localhost:3000/devtools/test_dashboard/index-mathjax3.html) and verify again that everything looks fine

…cript to reference mathjax v3/v4 instead of v2/v3

…roach, and migrate to v3/v4

…t of render, make sure raw input text is hidden at end of MathJax render, start render chain with Promise.resolve()

emilykl · 2026-07-10T19:03:59Z


+                // Now that the MathJax render has finished, re-hide the source text.
+                // We hid it earlier, too, but since this callback runs async,
+                // another function may have made it visible again


add a TODO to investigate this further

camdecoster · 2026-07-10T19:30:10Z

+        // Strip $…$ delimiters and clean up escape charaters,
+        // then pass the result to MathDocument.convert() to get an SVG element back
+        const texMath = cleanEscapesForTex(_texString).replace(/^\$+|\$+$/g, '');
+        return MathJax._.mathjax.mathjax.handleRetriesFor(function() {


Why is this call to handleRetriesFor required?

Found a page in the docs which explains it: https://docs.mathjax.org/en/v4.0/web/retry.html

From what I understand, it sounds like MathJax dynamically loads some features/extensions only as needed, and the internal synchronous functions are designed to error out if a required feature is not available, with a wrapper function catching the failure, loading the required feature, then retrying the function. The wrapper function returns a Promise which resolves when the wrapped function eventually completes successfully.

handleRetriesFor() is that wrapper function.

.convert() is a synchronous function, so wrapping it inside handleRetriesFor() has the additional impact of turning the call to .convert() into an asynchronous function.

camdecoster · 2026-07-10T19:38:15Z

-            MathJax.config.startup.output = 'svg';
+    var tmpDiv;
+
+    const initiateMathJax = function() {


Should this be an async function?

camdecoster · 2026-07-10T19:45:16Z

@@ -0,0 +1 @@
+- Add support for MathJax v4, and **drop support for v2** [[#7898](https://github.com/plotly/plotly.js/pull/7898)]


Suggested change

- Add support for MathJax v4, and **drop support for v2** [[#7898](https://github.com/plotly/plotly.js/pull/7898)]

- **Breaking:** Add support for MathJax v4, and **drop support for v2** [[#7898](https://github.com/plotly/plotly.js/pull/7898)]

camdecoster · 2026-07-10T19:49:13Z

Do you now why the legend got smaller?

camdecoster · 2026-07-10T19:52:33Z

Is the MathJax specifier supposed to be showing up in the pie chart? Is this the fallback behavior?

Co-authored-by: Cameron DeCoster <cameron.decoster@gmail.com>

emilykl changed the base branch from master to v4.0 July 10, 2026 12:18

emilykl added 6 commits July 10, 2026 08:32

update test dashboard, plot schema, package.json and make_baselines s…

047b56a

…cript to reference mathjax v3/v4 instead of v2/v3

update jasmine tests for mathjax v3/v4

367f430

bugfix: ticks relayout promise

b0d82d6

initial svg_text_utils refactor to use a better MathJax rendering app…

164ebfd

…roach, and migrate to v3/v4

bug fixes: disable automatic line breaks, capture text-anchor at star…

7e25bee

…t of render, make sure raw input text is hidden at end of MathJax render, start render chain with Promise.resolve()

update jasmine test

c9a3c3a

emilykl force-pushed the upgrade-mathjax-v3-v4-2 branch from 656d638 to 9c0b33c Compare July 10, 2026 12:33

update image baselines

83bb307

emilykl force-pushed the upgrade-mathjax-v3-v4-2 branch from 9c0b33c to 83bb307 Compare July 10, 2026 12:51

update make_exports script to use MathJax v4

88a77d5

emilykl marked this pull request as ready for review July 10, 2026 13:46

emilykl requested a review from camdecoster July 10, 2026 13:46

emilykl mentioned this pull request Jul 10, 2026

Bump MathJax support from v2/v3 to v3/v4 #7857

Closed

emilykl added 3 commits July 10, 2026 09:54

add draftlog

c262957

update mathjax section in readme

65683da

fix mathjax3 test dashboard

ae6b830

emilykl commented Jul 10, 2026

View reviewed changes

camdecoster reviewed Jul 10, 2026

View reviewed changes

Update src/lib/svg_text_utils.js

1a7ae8a

Co-authored-by: Cameron DeCoster <cameron.decoster@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Upgrade MathJax support from v2/v3 to v3/v4#7898

Upgrade MathJax support from v2/v3 to v3/v4#7898
emilykl wants to merge 12 commits into
v4.0from
upgrade-mathjax-v3-v4-2

emilykl commented Jul 10, 2026 •

edited

Loading

Uh oh!

emilykl Jul 10, 2026

Uh oh!

camdecoster Jul 10, 2026

Uh oh!

emilykl Jul 13, 2026

Uh oh!

Uh oh!

camdecoster Jul 10, 2026

Uh oh!

camdecoster Jul 10, 2026

Uh oh!

camdecoster Jul 10, 2026

Uh oh!

camdecoster Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -0,0 +1 @@
		- Add support for MathJax v4, and drop support for v2 [[#7898](https://github.com/plotly/plotly.js/pull/7898)]

	- Add support for MathJax v4, and drop support for v2 [[#7898](https://github.com/plotly/plotly.js/pull/7898)]
	- Breaking: Add support for MathJax v4, and drop support for v2 [[#7898](https://github.com/plotly/plotly.js/pull/7898)]

Uh oh!

Uh oh!

Conversation

emilykl commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Steps for testing

Uh oh!

emilykl Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

camdecoster Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

emilykl Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

camdecoster Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

camdecoster Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

camdecoster Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

camdecoster Jul 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

emilykl commented Jul 10, 2026 •

edited

Loading