Liqvid splits interactive video into a runtime core and a build pipeline

Two halves: a browser runtime and a video renderer

Liqvid is a library for creating interactive videos in React. The repository is a monorepo, and the README organises the packages into three groups that describe the split better than the package list alone does.

The frontend core holds six packages. The main package provides the main liqvid package. The host package is a script for pages hosting Liqvid videos, and currently just handles fake fullscreen. The keymap package provides the Keymap class, and the playback package provides the Playback class. The polyfills package holds polyfills for Liqvid videos and currently just handles Web Animations. The utils package provides the various helper functions in Utils.

The backend tools hold four. The cli package provides the Liqvid CLI tool. The magic package provides what the README calls wacky resource macro syntax. The renderer package handles the audio, build, render and thumbs CLI commands. The serve package is a development server and provides the serve command.

That architecture tells you most of what you need to know about the project. The browser side is small and focused: something that plays the video, something that interprets input, and a host script for the page. The heavy lifting of producing the actual video file happens on the command line, in a renderer that consumes the same resource model.

So this is not a React component you drop into a page and get a video. It is an authoring system with a compile step.

The resource macro syntax is the contract between the halves

The package that connects authoring to rendering is magic, described as providing a wacky resource macro syntax, and the CLI has a build command, a render command, an audio command and a thumbs command.

A resource macro syntax is the mechanism by which a piece of a video, an image, a sound, a formula or a segment of markup, is declared once and then referenced. The reason it exists is that both sides need to agree on the same resources. The browser runtime needs to know what to fetch and when, and the renderer needs to know what to draw into each frame.

This is the architectural heart of the project, and it is also the least documented part in the repository itself. The README links to the CLI macros documentation page and to per command pages for audio, build, render and thumbs, so the detail lives on the documentation site rather than in the repository.

The commands themselves have distinct jobs as their names suggest. The build command compiles the project into the artefacts the renderer consumes. The render command produces the video. The audio command deals with the audio track, and thumbs generates thumbnails.

The serve package provides a development server and the serve command, so you can run the project locally and iterate without rendering a full video each time. That is the loop you would live in, and it is the reason the development server is a separate package rather than a flag.

For anyone evaluating this project, the question to answer is what the macro syntax can express. The repository does not answer it, so the documentation site does.

Playback and Keymap are separate classes, not one component

The frontend core exposes Keymap and Playback as two named classes rather than folding everything into the main component, and the distinction tells you how the library is meant to be used.

A Keymap maps input to actions. A Playback controls the video timeline and the state that goes with it. Keeping them apart means the input handling can change without touching the playback logic, and it means you can drive the video programmatically without simulating keystrokes.

The utils package provides the various helper functions in Utils, and the README links to the Utils animation reference specifically, which suggests that animation timing helpers are a substantial part of what Utils covers. That fits the fake fullscreen and Web Animations polyfill packages: on mobile browsers, where a real fullscreen API is unavailable or unreliable, the library emulates the behaviour, and the animation helpers are what make a simulated fullscreen look right.

The polyfills package currently just handles Web Animations, and the host package currently just handles fake fullscreen. The word currently appears in both descriptions, which is a signal that these are the areas most likely to grow.

The mobile behaviour is the reason the docs have a mobile guide, and it is the practical difference between this library and a video tag. A plain video element on a phone is a rectangle. An interactive video needs the whole viewport, and needs to know that it is in a simulated fullscreen so that pointer and keyboard handling behave differently.

Integrations decide whether it fits your content

The integrations group holds two finished packages and a long in-development list, and the list is where the practical fit is decided.

The finished ones are katex, which provides KaTeX integration, and react-three, which provides a React Three Fiber integration. The React Three Fiber one is a strong signal about what kind of video this library is for. Three dimensional content in a video is a technique used for spatial explainers and for anything where camera movement through a scene carries meaning.

The in-development list is longer and mostly about content types. There is captioning for a captions editor, gsap for the GSAP animation library, with the README asking parenthetically whether it might already work, i18n for internationalisation utilities, player for a new Web Components based Player, mathjax for the MathJax integration, react which is probably for when Liqvid goes to Web Components in version 3, and xyjax for the XyJax integration.

Reading that list as a set of requirements tells you what kind of videos this library wants to make. Math formulas rendered with MathJax or XyJax, captions, multiple languages, and 3D scenes. That is instructional content, textbook style content, and course content.

The player entry is the strategically interesting one. The react package is described as probably for when Liqvid goes to Web Components in version 3, which means the project has a stated direction away from React only, towards a component model that works outside React. That is a long term bet, and it means the API you use today may look different later.

The build stack, and the fact that there is no published release

The root package.json describes the development setup rather than a published package, and reading it tells you what building Liqvid looks like.

The root is named root, is private, and declares workspaces for the packages directory.

  "name": "root",
  "private": true,
  "workspaces": ["packages/*"],

The package manager is pinned, and it is pnpm rather than npm or yarn.

  "packageManager": "[email protected]+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"

The dependency list is a build toolchain rather than runtime dependencies. Rollup is present with plugins for babel, commonjs, node-resolve, terser and dts, so the packages are bundled with type declaration files. Babel is there with the preset-env and the transform-modules-umd plugin, which is how a UMD build is produced. Jest with ts-jest and a jsdom environment, plus testing-library packages for react and dom and user-event, cover unit testing, and Playwright is present with an experimental component testing package for browser level testing. Biome is the linter and formatter at version 1.9.4, and TypeScript is at 5.7.3.

There is also a build.mjs file at the repository root, a pnpm-workspace.yaml alongside the pnpm lockfile, a tsconfig.json and a biome.json.

What is missing is a release. The repository publishes no GitHub releases, and the README gives no install command, so there is nothing to pin from the npm registry as far as this repository shows. The documentation site is the entry point for usage, and the repository is the source. The last push was on 2026-10-13, so the code is moving.

Where Liqvid is the wrong tool

The first limitation is the shape of the output. A Liqvid video is produced by rendering, through a CLI, from a source project. If you want a video element in a React page that plays an MP4 you already have, this library is enormous overkill, and the plain video tag is the right answer.

The second limitation is that the interesting features are in development. Captioning, internationalisation, the Web Components player, the GSAP integration and the React package for version 3 are all listed as in development. That is fine if you need them and can tolerate an unstable API, and it is disqualifying if your content pipeline needs them to be reliable today.

The third is the dependency on a renderer environment. The CLI pulls in nuget-like tooling of its own, and the build and render commands have to run somewhere with the right native dependencies. Nothing in the repository says the renderer is a pure JavaScript process, so a Node-only pipeline may need more than the package.json suggests.

The fourth is the maturity signal, or the lack of one. No releases, a version 3 plan mentioned in passing, and a package list where several entries carry the word currently or the word probably. This reads like an active project with real users, given the Discord and the docs, but like one where interfaces are still moving.

And the fifth is that the interesting content features are third party integrations. KaTeX, MathJax, XyJax, GSAP, React Three Fiber: each one is a dependency with its own version compatibility and its own failure modes, and the seams between them are where a video pipeline usually breaks.

How it compares with a video player component or a canvas animation tool

There are two nearby alternatives, and Liqvid sits between them.

The first is a React video player component. Those give you a styled player with controls, chapters, playback speed and analytics. Liqvid gives you something different: the video is a program that runs, with branches and state, and the controls are a Keymap you define. A player component plays one file; Liqvid renders a set of resources into a timeline.

The second is a canvas or WebGL animation tool, where you draw the video yourself in code. The advantage is total control over every frame. The disadvantage is that you are building a renderer, a timeline and an export path yourself, and Liqvid already has the export path, which is the hardest part.

The distinction that matters most in practice is whether the video is a recording of your application or a rendered artifact of your content. Liqvid is for the second kind. That means the source is a project you build and render, the output is deterministic, and the video is not a screen capture. For an explainer with synchronised narration, formulas and branching, that is the right shape.

Against a traditional video editor, Liqvid gives you version control and repeatability, and takes away the timeline you would use to place things by hand. For a team that produces many videos from structured content, that trade is usually worth it. For a one-off piece with heavy art direction, an editor is faster.

The honest summary is that Liqvid is a content compiler for instructional video, and the question to ask before adopting it is whether your videos are generated or filmed.

Editorial conclusion

Liqvid fits a team producing explainer or course style video where the viewer can branch, or where annotations and equations need to line up with the narration, and who are willing to build the video through a CLI rather than capture it in a screen recorder. It does not fit a project that needs a plain video element in a React app, since the whole approach is authoring plus rendering, and it does not fit a team that needs its integrations to be finished, because the captioning, gsap, i18n, player, mathjax, react and xyjax packages are all listed as in development. Before adopting, read the docs at liqvidjs.org/docs to see which of the frontend packages you would actually depend on, check whether the in-development integrations cover the features you need, and expect a setup that involves the CLI and a build step rather than a drop-in component.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. liqvidjs/liqvid on GitHub
4. Project website
5. README