react-katex

react-katex is a small React wrapper around KaTeX, the fast TeX/LaTeX rendering engine, exposing two components — InlineMath and BlockMath — that turn a LaTeX string into safely rendered HTML. Formulas can be passed either as a math prop or as JSX children, which makes it easy to use tagged template literals (String.raw) for multiline or backslash-heavy expressions without excessive escaping.

Parsing failures are handled explicitly: by default the library falls back to KaTeX’s own error rendering with a configurable errorColor, but consumers can supply a renderError callback to fully control what’s shown when a formula doesn’t parse. The library has no runtime dependencies beyond katex and prop-types, and requires manually importing KaTeX’s CSS file alongside the components.

What You Get

• InlineMath and BlockMath React components ready to import and render TeX/LaTeX
• Support for both prop-based (math=”…”) and children-based formula input
• Configurable error color and a custom renderError callback for parse failures
• A memoized rendering path that avoids re-running KaTeX on every render

Common Use Cases

• Embedding equations in React-based documentation, blogs, or knowledge bases
• Rendering formulas in educational apps, quizzes, and scientific calculators
• Displaying model or statistics formulas in data dashboards
• Building formula editors that need custom error feedback for invalid LaTeX

Under The Hood

Architecture The library is a thin wrapper implemented in a single ~90-line file (src/index.jsx) built around one factory function, createMathComponent, that takes an internal presentation component (InternalBlockMath or InternalInlineMath, differing only in whether they render a div or span) and a displayMode flag, returning a memoized function component. That component calls KaTeX.renderToString synchronously inside a useMemo keyed on the formula/errorColor/renderError, catching KaTeX.ParseError and TypeError to either delegate to a caller-supplied renderError callback or fall back to KaTeX’s own error HTML via dangerouslySetInnerHTML. There’s no internal state, context, or class hierarchy — it’s a pure computed-render pattern (props in, sanitized HTML out), and since BlockMath and InlineMath both funnel through the same factory, the coupling between the two public exports is small and intentional.

Tech Stack The only runtime dependency is katex (^0.16.0) for TeX parsing/rendering, with prop-types as a peer-adjacent runtime validator and React (>=15.3.2 <20, tested through React 18) as a peer dependency; there is no TypeScript, though JSDoc typedefs and @types/katex give editors some type hints. The repo is a Yarn 1 workspaces monorepo (packages/react-katex plus a packages/example demo app), built with @swc/cli/@swc/core compiling src/index.jsx straight to a single dist/react-katex.js bundle rather than going through a bundler like Rollup or webpack. ESLint (eslint:recommended + plugin:react/all) and Prettier enforce style, and Travis CI plus Coveralls are wired up in config, though the multi-year gap between releases suggests that CI pipeline is largely dormant today.

Code Quality Tests live under packages/react-katex/tests using Jest (via @swc/jest) with @testing-library/react and jest-dom matchers. A shared sharedExamples.js helper is parameterized over BlockMath and InlineMath so both components run through an identical suite — props vs. children input, prop updates, default and custom error handling, and an invalid-prop-type case — avoiding duplicated test logic between BlockMath.spec.js and InlineMath.spec.js. Error handling is explicit: KaTeX.ParseError and TypeError are caught deliberately and distinguished from unexpected errors, which are rethrown rather than swallowed. Naming is idiomatic React (PascalCase components, camelCase props), but with no TypeScript, type safety is enforced only at runtime via prop-types.

API Design The public surface is intentionally tiny — two components, each accepting a formula as either a math prop or as children, letting consumers pick whichever reads more naturally in JSX (a short attribute for simple formulas, tagged String.raw template literals for multiline/backslash-heavy TeX). Getting started needs exactly one non-obvious step beyond installing the package: manually importing katex/dist/katex.min.css, which the README calls out explicitly with worked examples and rendered screenshots for InlineMath, BlockMath, error handling, and escaping. There’s no configuration object, provider, or context requirement — about as low-boilerplate as a rendering library gets, aside from that manual CSS import.