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.

Closes #7598.

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

Modify src/lib/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
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)
  - Side note: This seems to be more or less the approach proposed here by @akhmerov in 2022
- 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._.mathjax namespace. While not officially documented, the pattern is used in several places (one, two, three) in the MathJax docs for advanced configuration
  - The MathJax API is mainly intended for rendering entire documents/pages in one shot, so it doesn't directly expose functions for rendering individual expressions one-at-a-time
- 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
- Exception: In the mathjax3__mathjax mock, the pie labels which were previously hidden, are now visible as raw MathJax. We don't support rendering MathJax in pie labels. Now at least the behavior is consistent between v3 and v4. However we could change the behavior to hide MathJax text strings in places where we don't support rendering MathJax.
Update all testing infrastructure to use MathJax v3 and v4 rather than v2 and v3.
- NOTE: I've done this by changing all v2 references to v4. This means that v4 is now the "default" in the CI, unless v3 is explicitly specified
- This includes some updates to the MathJax devtools dashboard homepages

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 us not supporting MathJax in pie labels; this is not new, and it's (somewhat) deliberate, to lock in 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()

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.

Thanks for the explanation!

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

…d larger than 16)

…ashboard index page for mathjax 4 chtml

emilykl · 2026-07-14T14:16:43Z

+                .style({
+                    overflow: 'visible',
+                    'pointer-events': 'none',
+                    'font-size': config.fontSize + 'px',


Note: this addition fixes a bug where MathJax expressions would not render larger than font size 16 in plotly

archmoj · 2026-07-15T17:49:13Z

+    "@plotly/mathjax-v3": "npm:mathjax@3.2.2",
+    "@plotly/mathjax-v4": "npm:mathjax@^4.1.2",


Here the caret (^) sign is removed for MathJax v3 pinning down the version of dependency. IMHO this is a good practice to avoid unwanted test breakages as a result of future minor/patch releases of MathJax v3.
If that's the case, then we should possibly do the same for MathJax v4 i.e.

"@plotly/mathjax-v4": "npm:mathjax@4.1.3",

Please note that the latest v4 is now at 4.1.3:
https://www.npmjs.com/package/mathjax?activeTab=versions

Did you have trouble with that in the past? If not, it seems fine to leave this unbounded and rely on the lock file to keep us in sync.

Yes I recall noticing baseline changes between MathJax v2 patch and minor releases.
If you decide to unpin mathjax-v4 then mathjax-v3 may also be reverted to the unpin version i.e.

"@plotly/mathjax-v3": "npm:mathjax@^3.2.2",

camdecoster

It's working for me. Good work!

camdecoster · 2026-07-15T17:57:15Z

+        // 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() {


Thanks for the explanation!

camdecoster · 2026-07-15T18:14:32Z

+    "@plotly/mathjax-v3": "npm:mathjax@3.2.2",
+    "@plotly/mathjax-v4": "npm:mathjax@^4.1.2",


Did you have trouble with that in the past? If not, it seems fine to leave this unbounded and rely on the lock file to keep us in sync.

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

Comment thread src/lib/svg_text_utils.js

camdecoster reviewed Jul 10, 2026

View reviewed changes

emilykl and others added 6 commits July 13, 2026 11:15

Update src/lib/svg_text_utils.js

1a7ae8a

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

Update draftlogs/7898_change.md

ce7bc22

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

add additional comments

ee4e480

resolve existing issue with font size for mathjax (font never appeare…

a26c12b

…d larger than 16)

update image baselines

aa4d1b4

add mathjax-font-size mock

5b03600

emilykl force-pushed the upgrade-mathjax-v3-v4-2 branch from dc176ac to 5b03600 Compare July 13, 2026 21:33

fix, simplify, and upgrade devtools dashboards for mathjax. Add new d…

19b432d

…ashboard index page for mathjax 4 chtml

emilykl commented Jul 14, 2026

View reviewed changes

archmoj reviewed Jul 15, 2026

View reviewed changes

Comment thread draftlogs/7898_change.md Outdated

camdecoster approved these changes Jul 15, 2026

View reviewed changes

emilykl added 2 commits July 16, 2026 13:30

relax mathjax v3 dev pin

696541d

add additonal draftlogs

99d55cb

		"@plotly/mathjax-v3": "npm:mathjax@3.2.2",
		"@plotly/mathjax-v4": "npm:mathjax@^4.1.2",

Uh oh!

Uh oh!

Conversation

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

Uh oh!

Steps for testing

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

camdecoster left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

emilykl commented Jul 10, 2026 •

edited by camdecoster

Loading