@instantshader/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InstantGradient (instantgradient.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @instantshader/react
+
+React bindings for [instantshader](https://www.npmjs.com/package/instantshader), a
+zero-dependency animated WebGL gradient engine. Drop a `<Flow>` or `<Beam>`
+component into any sized wrapper to mount a live, animated gradient. Built by
+[InstantGradient](https://instantgradient.com/shaders).
+
+## Install
+
+```bash
+npm install @instantshader/react
+```
+
+## Usage
+
+```tsx
+import { Flow } from "@instantshader/react";
+
+export function Background() {
+  return (
+    <Flow
+      colors={["#4f46e5", "#ec4899", "#22d3ee"]}
+      style={{ width: "100%", height: "100%" }}
+    />
+  );
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { CSSProperties, ReactElement } from "react";
+import { ParamDef, ShaderDef, ShaderDef as ShaderDef$1, beam, flow } from "instantshader";
+
+//#region src/ShaderCanvas.d.ts
+interface ShaderCanvasProps {
+  shader: ShaderDef$1;
+  colors: string[];
+  /**
+  * Merged into the shader's current params (removed/omitted keys are NOT
+  * reset to their default — they keep whatever value was last applied).
+  * Setting this prop back to `undefined` does not revert to defaults
+  * either: the underlying MountHandle is only updated when `params` is
+  * truthy, so the last applied values simply stick.
+  */
+  params?: Record<string, number>;
+  /**
+  * Setting this prop back to `undefined` does NOT revert playback to the
+  * default speed — the underlying MountHandle is only updated when `speed`
+  * is not `undefined`, so whatever speed was last applied keeps playing.
+  */
+  speed?: number;
+  seed?: number;
+  paused?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+/**
+* Mounts a live InstantShader gradient into a wrapper `<div>`. The canvas
+* fills that div at 100%/100% (mountGradient styles it that way), so the
+* consumer MUST give the wrapper an explicit size (via `style`, `className`,
+* or a sized parent) — this component does not impose one beyond
+* `position: relative`.
+*/
+declare function ShaderCanvas({
+  shader,
+  colors,
+  params,
+  speed,
+  seed,
+  paused,
+  className,
+  style
+}: ShaderCanvasProps): ReactElement;
+//#endregion
+//#region src/shaders.d.ts
+declare function Flow(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
+declare function Beam(props: Omit<ShaderCanvasProps, "shader">): ReactElement;
+//#endregion
+export { Beam, Flow, type ParamDef, ShaderCanvas, type ShaderCanvasProps, type ShaderDef, beam, flow };

package/dist/index.js

@@ -0,0 +1,74 @@
+"use client";
+import { useEffect, useMemo, useRef } from "react";
+import { beam, beam as beam$1, flow, flow as flow$1, mountGradient } from "instantshader";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/ShaderCanvas.tsx
+/**
+* Mounts a live InstantShader gradient into a wrapper `<div>`. The canvas
+* fills that div at 100%/100% (mountGradient styles it that way), so the
+* consumer MUST give the wrapper an explicit size (via `style`, `className`,
+* or a sized parent) — this component does not impose one beyond
+* `position: relative`.
+*/
+function ShaderCanvas({ shader, colors, params, speed, seed, paused, className, style }) {
+	const containerRef = useRef(null);
+	const handleRef = useRef(null);
+	const p = useMemo(() => params, [params ? Object.entries(params).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${k}:${v}`).join(",") : ""]);
+	useEffect(() => {
+		const container = containerRef.current;
+		if (!container) return;
+		const handle = mountGradient(container, {
+			shader,
+			colors,
+			params: p,
+			speed,
+			seed
+		});
+		handleRef.current = handle;
+		if (paused) handle.pause();
+		return () => {
+			handle.dispose();
+			handleRef.current = null;
+		};
+	}, [shader, seed]);
+	useEffect(() => {
+		handleRef.current?.setColors(colors);
+	}, [colors]);
+	useEffect(() => {
+		if (p) handleRef.current?.setParams(p);
+	}, [p]);
+	useEffect(() => {
+		if (speed !== void 0) handleRef.current?.setSpeed(speed);
+	}, [speed]);
+	useEffect(() => {
+		if (paused) handleRef.current?.pause();
+		else handleRef.current?.resume();
+	}, [paused]);
+	return /* @__PURE__ */ jsx("div", {
+		ref: containerRef,
+		className,
+		style: {
+			position: "relative",
+			...style
+		}
+	});
+}
+
+//#endregion
+//#region src/shaders.tsx
+function Flow(props) {
+	return /* @__PURE__ */ jsx(ShaderCanvas, {
+		shader: flow$1,
+		...props
+	});
+}
+function Beam(props) {
+	return /* @__PURE__ */ jsx(ShaderCanvas, {
+		shader: beam$1,
+		...props
+	});
+}
+
+//#endregion
+export { Beam, Flow, ShaderCanvas, beam, flow };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@instantshader/react",
+  "version": "0.1.0",
+  "description": "React bindings for InstantShader animated WebGL gradients.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ugolbck/instantshader.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://instantgradient.com/shaders",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "webgl",
+    "shader",
+    "gradient",
+    "mesh-gradient",
+    "animated-gradient",
+    "react"
+  ],
+  "dependencies": {
+    "instantshader": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint:pkg": "publint && attw --pack . --profile esm-only"
+  }
+}