# rod2ik/TikZJax
[](https://github.com/rod2ik/tikzjax)
[](https://www.npmjs.com/package/@rod2ik/tikzjax)
[](https://www.gnu.org/licenses/gpl-3.0)
[](themes.md)
[](themes.md#adaptive-explicit-colors-in-dark-mode)
[](parallel-rendering.md)
[](#supported-optional-packages)
[](architecture.md)
**TikZJax** renders **TikZ and supported TikZ-based LaTeX packages directly in the browser**.
It focuses on singular TikZ-based LaTeX packages, that do NOT already exist on:
* **MathJax**,
* neither on other main web drawing libraries, e.g. **Graphviz**, or **Mermaid**, etc..
It can be used inside:
* standalone HTML pages;
* MkDocs documentation;
* Material for MkDocs sites;
* static websites;
* other browser-based documentation systems.
TikZJax runs TeX through WebAssembly inside Web Workers. It does not require a server-side LaTeX installation or a remote rendering service.
---
## Documentation and test projects
| Resource | Link |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| Documentation and live demonstration site | [rod2ik.github.io/tikzjax](https://rod2ik.github.io/tikzjax) |
| Minimal MkDocs test repository | [rod2ik/minimal-mkdocs-tikzjax](https://github.com/rod2ik/minimal-mkdocs-tikzjax) |
| Source repository | [rod2ik/tikzjax](https://github.com/rod2ik/tikzjax) |
| npm package | [@rod2ik/tikzjax](https://www.npmjs.com/package/@rod2ik/tikzjax) |
| jsDeliver CDN | [@rod2ik/tikzjax](https://www.jsdelivr.com/package/npm/@rod2ik/tikzjax) |
The minimal MkDocs repository can be cloned and run locally to test the integration in an isolated project.
---
## Examples
### Pure TikZ
### tkz-tab
### Physics
### Circuitikz
### Kinematikz
### Chemfig
### Yquant
### Tikz-feynhand
### Braids
### Pgf-spectra
---
## Project lineage
`rod2ik/TikZJax` is based on the historical great works 👏👏👏 of:
* [kisonecat/tikzjax](https://github.com/kisonecat/tikzjax), created by [Jim Fowler](https://github.com/kisonecat);
* [drgrice1/tikzjax](https://github.com/drgrice1/tikzjax), created by [Glenn Rice](https://github.com/drgrice1).
Those projects are themselves based on browser ports of TeX and DVI conversion tools.
This project uses its own related forks:
* [rod2ik/web2js](https://github.com/rod2ik/web2js);
* [rod2ik/dvi2html](https://github.com/rod2ik/dvi2html).
The original projects provided the foundation for rendering TikZ in a browser. This fork preserves that capability while adding a larger configuration, package, documentation, performance, and integration layer.
---
## Visual feature badges
The following Shields badges identify the origin of the features described on this page:
* [](https://github.com/rod2ik/tikzjax) inherited from the historical TikZJax projects;
* [](https://github.com/rod2ik/tikzjax) inherited behavior substantially expanded in this fork;
* [](https://github.com/rod2ik/tikzjax) functionality added by `rod2ik/TikZJax`.
The badges are ordinary linked images generated by [Shields.io](https://shields.io/) and render correctly in Material for MkDocs.
---
## Supported optional packages
The distributed browser runtime includes the files required by all of these optional packages:
[](examples/tkz-tab.md)
[](examples/physics.md)
[](examples/circuitikz.md)
[](examples/chemfig.md)
[](examples/yquant.md)
[](examples/tikz-feynhand.md)
[](examples/pgf-spectra.md)
[](examples/kinematikz.md)
```json
[
"tkz-tab",
"physics",
"circuitikz",
"chemfig",
"yquant",
"tikz-feynhand",
"pgf-spectra",
"kinematikz"
]
```
The runtime files are available, but packages are loaded into a diagram only when declared globally or with `data-tex-packages`.
```html
```
See the [complete examples catalogue](examples/index.md).
---
## What is different in `rod2ik/TikZJax`?
### Core rendering
* [](https://github.com/rod2ik/tikzjax) Browser-side TikZ rendering through TeX compiled to WebAssembly.
* [](https://github.com/rod2ik/tikzjax) Support for `
```
### unpkg
```html
```
### npm
```bash
npm install @rod2ik/tikzjax
```
### Yarn
```bash
yarn add @rod2ik/tikzjax
```
See:
* [Installation overview](site/docs/installation/index.md);
* [Standalone HTML installation](site/docs/installation/html.md);
* [MkDocs installation](site/docs/installation/mkdocs.md).
---
## Recommended configuration
```js
window.TikzJaxOptions = {
renderTimeout: 30000,
maxRetries: 1,
restartWorkerOnFail: true,
workerPool: {
enabled: true,
maxWorkers: 3,
reserveCpuCores: 1,
useDeviceMemory: true,
initializationRetries: 1
}
};
```
This enables:
* [](https://github.com/rod2ik/tikzjax) bounded parallel rendering;
* [](https://github.com/rod2ik/tikzjax) adaptive worker-pool sizing;
* [](https://github.com/rod2ik/tikzjax) worker initialization retries;
* [](https://github.com/rod2ik/tikzjax) rendering retries;
* [](https://github.com/rod2ik/tikzjax) failed-worker replacement;
* [](https://github.com/rod2ik/tikzjax) finite rendering timeouts.
See [Configuration](site/docs/configuration.md).
---
## Basic TikZ example
### HTML syntax
[](https://github.com/rod2ik/tikzjax), retained and extended:
```html
```
On the documentation site, TikZJax replaces this source with a generated SVG.
---
### MkDocs fenced syntax
[](https://github.com/rod2ik/tikzjax) in `rod2ik/TikZJax`:
````markdown
```tikzjax
\begin{tikzpicture}
\draw[->,very thick]
(0,0) -- (4,0)
node[right] {$x$};
\draw[->,very thick]
(0,0) -- (0,3)
node[above] {$y$};
\draw[very thick]
(0,0) -- (3,2);
\end{tikzpicture}
```
````
Fenced blocks use globally configured packages and TikZ libraries.
Use an HTML source block when local `data-*` configuration is required.
---
## `tkz-tab` example
Native `tkz-tab` rendering is [](https://github.com/rod2ik/tikzjax) in `rod2ik/TikZJax`.
```html
```
Package loading and table configuration are separate:
```html
data-tex-packages="tkz-tab"
data-tkz-tab='{ ... }'
```
With `autoApply` enabled, the source does not need to repeat native `lw`, `lgt`, `espcl`, or node-font settings.
See the [`tkz-tab` examples](site/docs/examples/tkz-tab.md).
---
## Optional package example
Per-diagram package loading is [](https://github.com/rod2ik/tikzjax).
```html
```
Several packages or package options can be declared with compact JSON:
```html
```
See [Global and Local Configuration](site/docs/configuration-scopes.md).
---
## TikZ library example
Per-diagram TikZ libraries are [](https://github.com/rod2ik/tikzjax).
```html
```
TikZ libraries and LaTeX packages use separate configuration fields.
For example, `braids` is a TikZ library:
```html
data-tikz-libraries="braids"
```
---
## Light and dark themes
Theme adaptation is [](https://github.com/rod2ik/tikzjax).
TikZJax can update already-rendered and cached SVGs after a theme change without recompiling TeX.
### Adaptive explicit colors
Explicit chromatic SVG colors are adapted automatically in Dark mode through `theme.adaptiveColors`, which is enabled by default.
Instead of applying a literal RGB negative, TikZJax raises perceptual lightness while keeping each color in the same visual family. Saturation can also be reinforced so dark blues, reds, greens, and other colors become clear, vivid dark-mode variants rather than pale greyish colors.
The red, green, and blue color families have configurable hue shifts. By default, deep blues are shifted towards a clearer sky-blue range.
The main defaults can be written explicitly as:
```js
window.TikzJaxOptions = {
theme: {
adaptiveColors: {
enabled: true,
strength: 1,
hueShift: {
red: 0,
green: 0,
blue: -40
},
contrast: {
enabled: true,
minimumRatio: 4.5
}
}
}
};
```
This configuration block is optional because these values are already enabled by default.
In Light mode, TikZJax restores the original chromatic SVG values. The existing special handling of black, white, `currentColor`, transparent paints, gradients, and patterns remains separate and unchanged.
Set `theme.adaptiveColors` to `false` to disable explicit-color adaptation and its contrast stage.
### Automatic foreground/background contrast
In Dark mode, TikZJax can estimate the visible contrast in three common SVG arrangements:
* text painted over a filled shape;
* a bright neutral `stroke` belonging to the same element as its background `fill`;
* a small bright-neutral vector detail painted over a larger filled shape.
If the ratio is below `theme.adaptiveColors.contrast.minimumRatio`, the detected background fill is darkened until the requested contrast is approached.
The default requested ratio is `4.5`. The foreground text, outline, or vector detail is not replaced by this contrast stage. Chromatic vector accents, such as a red target point, do not trigger the bright-neutral heuristic, and page components outside generated TikZJax SVGs are not restyled.
No additional configuration option is required for this expanded foreground detection.
A background modified by this stage can be identified in the generated SVG by:
```html
data-tikzjax-contrast-adjusted="true"
```
### Material for MkDocs
A Material configuration can use:
```js
window.TikzJaxOptions = {
theme: {
selector: "body",
applyTargetStyles: false,
attribute: "data-md-color-scheme",
darkValue: "slate",
lightValue: "default",
fallbackTheme: "light",
followSystemTheme: true
}
};
```
`applyTargetStyles` defaults to `false`. Material therefore remains responsible for the page background, text, navigation, cards, code blocks, tables, and admonitions.
The adaptive-color and SVG-contrast stages still apply to TikZJax diagrams in Dark mode; they do not require TikZJax to restyle the Material page itself.
### Standalone HTML
A custom standalone page can ask TikZJax to style one or more selected targets:
```js
window.TikzJaxOptions = {
theme: {
selector: ".app",
applyTargetStyles: true,
lightBackgroundColor: "#ffffff",
lightTextColor: "#000000",
darkBackgroundColor: "#1b1e2b",
darkTextColor: "#ffffff",
darkClass: "dark",
lightClass: "light",
attribute: "data-theme",
darkValue: "dark",
lightValue: "light"
}
};
```
`theme.selector` accepts any valid CSS selector. Every matching target receives the resolved background and text colors only when `applyTargetStyles` is enabled.
See [Light and Dark Themes](site/docs/themes.md) and the [standalone advanced example](site/docs/installation/advanced.html).
---
## Parallel rendering
The adaptive Web Worker pool is [](https://github.com/rod2ik/tikzjax).
```text
global render queue
|
+-- worker 1 --> diagram A
+-- worker 2 --> diagram B
+-- worker 3 --> diagram C
```
The pool:
* renders independent diagrams concurrently;
* limits the maximum number of workers;
* reserves CPU capacity for the browser;
* can account for device memory;
* initializes workers lazily;
* replaces failed workers;
* prioritizes visible diagrams;
* avoids compiling identical pending jobs several times.
See [Parallel Rendering and the Worker Pool](site/docs/parallel-rendering.md).
---
## Cache and performance
Browser-side SVG caching is an [](https://github.com/rod2ik/tikzjax) historical capability.
The current implementation also provides:
* [](https://github.com/rod2ik/tikzjax) rendering identities based on exact source and effective options;
* [](https://github.com/rod2ik/tikzjax) pending-job deduplication;
* [](https://github.com/rod2ik/tikzjax) worker-local TeX dependency caches;
* [](https://github.com/rod2ik/tikzjax) worker runtime reuse;
* [](https://github.com/rod2ik/tikzjax) viewport-priority scheduling;
* [](https://github.com/rod2ik/tikzjax) local cache bypass.
Disable the persistent SVG cache for one debugging block with:
```html
data-disable-cache="true"
```
See [Cache and Performance](site/docs/cache-performance.md).
---
## Error handling
Timeout, retry, and worker-restart behavior are [](https://github.com/rod2ik/tikzjax).
Custom fallback images are [](https://github.com/rod2ik/tikzjax).
```js
window.TikzJaxOptions = {
renderTimeout: 30000,
maxRetries: 1,
restartWorkerOnFail: true,
brokenImageSrc:
"https://cdn.jsdelivr.net/npm/@rod2ik/tikzjax@__TIKZJAX_VERSION__/dist/assets/broken-image.svg"
};
```
A local fallback can be configured with:
```html
data-broken-image-src="/assets/images/local-error.svg"
```
See [Fallback and Error Images](site/docs/fallback-error-images.md).
---
## Intentionally invalid example
The following source is intentionally invalid so that the fallback path can be tested.
Using a complete document with an undefined command produces a more predictable failure than omitting an environment terminator.
```html
```
The configured fallback image should appear after all permitted attempts fail.
---
## Local development
TikZJax development uses **Yarn 4.17.1** through Corepack and keeps the `node_modules` linker for compatibility with the Webpack toolchain.
Quick start:
```bash
corepack enable
yarn install --immutable
yarn dev
```
`yarn dev` uses the incremental local vendor workflow: TikZJax is rebuilt only when configured build inputs changed, `dist/` is synchronized to `site/overrides/vendor/tikzjax/` only when necessary, and MkDocs then loads that local vendor. Documentation-only edits do not rebuild TikZJax.
The standalone Webpack playground remains separate:
```bash
yarn playground
# short alias
yarn pg
```
For the complete development workflow, command reference, vendor architecture, Web2js handoff, documentation conventions, validation, and releases, see the **canonical MkDocs development section**:
- [Development overview](site/docs/development/index.md)
- [Yarn scripts](site/docs/development/yarn-scripts.md)
- [Vendor system](site/docs/development/vendor-system.md)
- [Web2js integration](site/docs/development/web2js-integration.md)
- [Documentation site development](site/docs/development/documentation-site.md)
- [Build and validation](site/docs/development/build-validation.md)
- [Release workflow](site/docs/development/release-workflow.md)
---
## Documentation
### Getting started
* [Installation overview](site/docs/installation/index.md)
* [Standalone HTML installation](site/docs/installation/html.md)
* [MkDocs installation](site/docs/installation/mkdocs.md)
* [Configuration](site/docs/configuration.md)
* [Global and Local Configuration](site/docs/configuration-scopes.md)
### Rendering and performance
* [Parallel Rendering and the Worker Pool](site/docs/parallel-rendering.md)
* [Cache and Performance](site/docs/cache-performance.md)
* [Runtime Architecture](site/docs/architecture.md)
### Appearance and errors
* [Light and Dark Themes](site/docs/themes.md)
* [Fallback and Error Images](site/docs/fallback-error-images.md)
* [Troubleshooting](site/docs/troubleshooting.md)
### Reference and examples
* [API Reference](site/docs/api-reference.md)
* [Examples](site/docs/examples/index.md)
* [Standalone advanced HTML example](site/docs/installation/advanced.html)
* [TikZ examples](site/docs/examples/tikz.md)
* [`tkz-tab` examples](site/docs/examples/tkz-tab.md)
* [`physics` examples](site/docs/examples/physics.md)
* [`circuitikz` examples](site/docs/examples/circuitikz.md)
* [`chemfig` examples](site/docs/examples/chemfig.md)
* [`yquant` examples](site/docs/examples/yquant.md)
* [`tikz-feynhand` examples](site/docs/examples/tikz-feynhand.md)
* [`pgf-spectra` examples](site/docs/examples/pgf-spectra.md)
* [`kinematikz` examples](site/docs/examples/kinematikz.md)
---
## Credits
TikZJax exists because of the foundational work of the original TikZJax, Web2JS, and DVI-to-HTML projects and their contributors.
`rod2ik/TikZJax` preserves the original browser-side TikZ rendering concept while adding [](https://github.com/rod2ik/tikzjax) functionality for:
* `tkz-tab`;
* optional package loading;
* global and local configuration;
* MkDocs fenced blocks;
* light and dark themes, including adaptive chromatic colors and automatic foreground/background SVG contrast correction;
* adaptive parallel rendering;
* dynamic content;
* expanded caching;
* diagnostics;
* fallback images.
Please also visit and credit the upstream projects:
* [kisonecat/tikzjax](https://github.com/kisonecat/tikzjax);
* [drgrice1/tikzjax](https://github.com/drgrice1/tikzjax).