Paper Shaders: canvas shaders as npm packages for React and vanilla JS

The problem Paper Shaders solves, and who it is actually for

Most teams that want a moving gradient or a dotted orbit behind a hero section face the same choice. Write raw WebGL, which means shader source, uniform plumbing, a render loop and context-loss handling. Or drop in a heavier animation library and accept the bundle cost. Paper Shaders sits in that gap. The README describes the packages as "zero-dependency HTML canvas shaders that can be installed from npm or designed in Paper," and the stated goal is to "give designers a visual way to use common shaders in their designs" with output that is "directly exportable as lightweight code that works in any codebase."

The intended audience is visible in the repository layout. There are two published workspaces, packages/shaders and packages/shaders-react, plus a docs workspace that powers the interactive examples at shaders.paper.design. Framework support is listed as vanilla JS and React JS, with Vue and others left to future community PRs. So the fit is a front-end team on React, or a plain-JS site, that wants a named effect rather than an animation engine. The README also frames the use case narrowly: texture for backgrounds, or effects masked with shapes and text. This is decoration with a defined job, not a general graphics toolkit.

How the shader components work: props in, canvas out

The mechanism is a component that owns a canvas and renders a WebGL effect into it. You pass colors as an array of CSS color strings and control the animation with numeric props. The README's React example uses MeshGradient with colors, distortion, swirl and speed, and DotOrbit with colors, colorBack and scale. Styling is passed through a style object, so width and height come from ordinary React style props rather than a shader-specific sizing API.

That shape tells you most of what you need to know about integration. There is no scene graph, no timeline and no imperative handle documented in the README. Each component is a self-contained visual unit you place in the tree. The README notes that "these settings can be configured in code or designed in Paper," which is the core workflow claim: a designer tunes the same parameters in the visual editor and hands back values that map onto the component props. The repository confirms the two-package split through its workspaces array, so the React package is a wrapper layer over the vanilla one rather than a separate implementation. What the README does not document is the render loop internals, how the canvas resizes, or what happens when WebGL is unavailable. Those are the questions to answer by reading the source in packages/shaders before you depend on it.

Installing @paper-design/shaders-react and rendering a first shader

Installation is a single npm command per target. The README gives two package names depending on your stack, and adds a warning worth reading twice: "Please pin your dependency, we will ship breaking changes under 0.0.x versioning." Pin the exact version in package.json rather than using a caret range.

npm i @paper-design/shaders-react

For a vanilla JS project the package is different.

npm i @paper-design/shaders

With the React package installed, import the components you need and render them with props. This is the README's own example, trimmed to one component.

import {MeshGradient} from '@paper-design/shaders-react';

<MeshGradient
    colors={['#5100ff', '#00ff80', '#ffcc00', '#ea00ff']}
    distortion={1}
    swirl={0.8}
    speed={0.2}
    style={{width: 200, height: 200}}
/>

What you should see is a 200 by 200 animated mesh gradient using those four colors, with the distortion, swirl and speed values shaping the motion. Swapping in DotOrbit with its own colors, colorBack and scale props gives a dot field over a black background. There is no build step specific to the shaders and no CSS import mentioned in the README, so the components should render wherever React renders. If you are working in the monorepo itself rather than consuming the packages, the top-level scripts are bun run build and bun run dev:docs for the documentation site.

The 0.0.x versioning is the real adoption risk

The README is unusually direct about this, and it deserves to be the deciding factor in your evaluation. Breaking changes are expected within the 0.0.x range. In semantic versioning terms that range carries no compatibility promise at all, which means a patch bump can rename a prop or change a default. The repository has no retrieved releases, so there is no published changelog entry set to diff against here; the README points to CHANGELOG.md in the repository root, and that file is where you would confirm what moved between versions.

The practical consequence is that a Paper Shaders upgrade is a code change, not a routine dependency refresh. If your shader props are spread across a dozen components, every bump is a manual audit. The second limitation is scope. The README lists vanilla JS and React JS only. Vue, Svelte and the rest are explicitly future work, so a non-React framework means either consuming the vanilla package directly and writing your own wrapper, or waiting. The third is that the README documents props but not failure behaviour. Nothing in it describes a fallback when WebGL is unavailable or when the canvas is off-screen, and nothing describes how the animation loop is paused. On a page with several shaders, that is the difference between a decorative background and a battery drain on mobile, and the README is silent on it.

Paper Shaders versus writing your own WebGL or using an animation library

The alternative most teams actually weigh is a general-purpose animation or graphics library, where you compose the effect yourself and keep full control over the render loop, pausing and fallbacks. The difference in approach is the axis of control. A general library gives you the loop; Paper Shaders gives you the effect. If your requirement is a mesh gradient that a designer tuned in Paper, the second is less code and fewer decisions. If your requirement is a shader that reacts to scroll position, pointer velocity or data, you will be writing the same uniform plumbing the library was meant to save you, and a general library is the better fit.

The other alternative is doing nothing: a static CSS gradient or an SVG. It costs nothing at runtime, has no WebGL dependency and never breaks on a device with a weak GPU. Paper Shaders earns its place when the motion is part of the design intent, which is exactly the framing the README uses when it says the shaders are "animated (or not, your choice)." Note that last part. If you want a static version of one of these effects, the same components cover it, and that is a cheaper decision than reaching for a different tool.

Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-17, six days before this writing, so the project is being worked on now. That is a snapshot, not a promise. There are no retrieved releases, so the release cadence cannot be judged from the README; the CHANGELOG.md file in the repository root is the place to look.

Licensing is Apache-2.0, which the README spells out in plain terms. Commercial use in websites, apps, games, videos, prototypes and internal tools is permitted without visible attribution. The one condition stated is redistribution: if you ship Paper Shaders code inside another shader library, plugin or tool, preserve the included LICENSE and NOTICE files. The README adds that visible credit such as "Powered by Paper Shaders" is appreciated but framed as optional. Copyright is held by Lost Coast Labs, Inc. This is a summary of what the README says, not legal advice; if you are redistributing the code inside a product, read the LICENSE and NOTICE files in the repository.

The upgrade cost follows from the versioning policy. Budget for reading CHANGELOG.md and re-testing each shader's props on every bump, and pin the version in your lockfile so an install does not move it for you. The repository's own publish flow is manual on version numbers: the README instructs maintainers to bump versions by hand, build with bun run build and publish with bun run publish-all. Manual version bumps are a normal source of missed changelog entries, which is a reason to test rather than trust the notes alone.

Editorial conclusion

Adopt Paper Shaders if you want animated canvas texture on a marketing site and you are willing to pin an exact 0.0.x version and re-check the changelog before every upgrade. Do not adopt it if you need a stable public API with semantic version guarantees, or if a static CSS gradient already carries the design. Before you commit, verify three things: that the shader you want is exported by the package you installed, that your target browsers handle the canvas output, and that your lockfile pins the version rather than a caret range.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. paper-design/shaders on GitHub
4. Project website
5. README