Skip to content

README.md

Latest commit

 

History

History
92 lines (62 loc) · 4.41 KB

README.md

File metadata and controls

92 lines (62 loc) · 4.41 KB
Raw

RaTeX Web (WASM + Web-Render)

Use RaTeX in the browser: Rust compiled to WASM handles parsing and layout; TypeScript web-render draws on Canvas 2D from the DisplayList.

Note: For web projects we recommend using KaTeX directly — it is the mature, optimized choice for browser math rendering. This WASM build is not intended as the best solution for production web; it exists mainly for cross-platform comparison and testing (same RaTeX engine as iOS/Android, different render path).

Architecture

  • ratex-wasm (crates/ratex-wasm): Rust → WASM, exports the backward-compatible renderLatex(latex, color?, displayMode?) and the forward-compatible renderLatexWithOptions(latex, options?), both returning DisplayList JSON. displayMode defaults to true; pass false for inline/text style.
  • web-render (src/renderer.ts): Renders the DisplayList to Canvas 2D. GlyphPath items are drawn via Canvas fillText using char_code and the loaded KaTeX font; the page must load a math font (bundled fonts.css covers this).
  • Entry (src/index.ts): Initializes WASM and provides typed options-object overloads plus the existing positional APIs.

Out of the box

No build required — use the published npm package:

  1. Install — npm install ratex-wasm (or yarn add ratex-wasm).
  2. Use — see Drop-in Web Component below.

Build

Prerequisites: wasm-pack (and the Rust toolchain) must be installed. Running npm run build without it will error.

# Install wasm-pack: https://rustwasm.github.io/wasm-pack/installer/
cd platforms/web
npm install   # installs katex devDependency for font copy
npm run build # copy-fonts → build:wasm (generates pkg/) → build:ts

Output: pkg/ (WASM) and fonts/ (KaTeX woff2/woff, used by fonts.css).

Usage

Drop-in Web Component: <ratex-formula>

No bundler required — works with any framework or plain HTML.

<!-- 1. Fonts (once; the component also attempts auto-injection) -->
<link rel="stylesheet" href="node_modules/ratex-wasm/fonts.css" />

<!-- 2. Register the custom element -->
<script type="module" src="node_modules/ratex-wasm/dist/ratex-formula.js"></script>

<!-- 3. Use it -->
<ratex-formula latex="\frac{-b \pm \sqrt{b^2-4ac}}{2a}" font-size="48" padding="16" color="#1E88E5"></ratex-formula>
<ratex-formula latex="x^2 + y^2 = z^2" display-mode="false"></ratex-formula>

Supported attributes: latex, font-size, padding, background-color, color, display-mode ("true" by default; use "false" for inline/text style). You can also set element.latex = '...' and element.displayMode = false via JS.

In React: Use the DOM tag directly; React 18+ renders custom elements correctly. To pass a string, use a ref to set el.latex = '...' (preferred over dangerouslySetInnerHTML).

In Vue: Vue 3 treats non-Vue tags as custom elements by default. To configure explicitly: app.config.compilerOptions.isCustomElement = (tag) => tag === 'ratex-formula' (optional in Vue 3.2+).

Option 1: TypeScript/ESM (Programmatic API)

import { initRatex, renderLatexToCanvas } from './index.js';

await initRatex();
const canvas = document.querySelector('canvas');
renderLatexToCanvas('\\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}', canvas, {
  fontSize: 48,
  padding: 16,
  backgroundColor: 'white',
}, '#1E88E5');

Note: The page must load a math font, or letters/numbers will show as boxes. You can use KaTeX’s CSS (see repo-root demo/) or provide Latin Modern Math. This package bundles KaTeX fonts (no CDN): use <link rel="stylesheet" href="node_modules/ratex-wasm/fonts.css" /> or import 'ratex-wasm/fonts.css'; and fonts load from the package.

Option 2: DisplayList JSON only

import { initRatex, renderLatex, renderLatexWithOptions } from './index.js';

await initRatex();
const json = renderLatex('x^2 + y^2 = z^2', '#1E88E5');
const displayList = JSON.parse(json);

// Preferred: forward-compatible options object with exact normalized RGBA.
const inlineJson = renderLatexWithOptions('\\frac{1}{2}', {
  displayMode: false,
  color: { r: 0.12, g: 0.53, b: 0.9, a: 0.75 },
});

// The package entry also supports the equivalent renderLatex(latex, options) overload.

// Existing positional calls remain supported.
const legacyInlineJson = renderLatex('\\frac{1}{2}', undefined, false);