--- name: react description: React wrapper for @sarmal/core. Use when adding animated loading indicators with @sarmal/react — covers the Sarmal, SarmalSVG, and SarmalDotMatrix components, their hooks, init vs runtime props, curve morphing, and instance access. license: MIT --- # @sarmal/react React wrapper for `@sarmal/core`. Provides three components and matching lower-level hooks: | Component | Hook | Renderer | | ------------------- | -------------------- | ------------------------- | | `<Sarmal>` | `useSarmal` | Canvas — continuous trail | | `<SarmalSVG>` | `useSarmalSVG` | SVG — scales with CSS | | `<SarmalDotMatrix>` | `useSarmalDotMatrix` | Canvas — dot/pixel grid | Read `@sarmal/core` SKILL.md first for coordinate spaces, curve names, and shared option semantics. ## Installation ```bash npm install @sarmal/core @sarmal/react ``` ## Entry points ```ts import { Sarmal, SarmalSVG, SarmalDotMatrix, useSarmal, useSarmalSVG, useSarmalDotMatrix, } from "@sarmal/react"; ``` ## `"use client"` — required in RSC environments All exports in this package are client-only. Add `"use client"` at the top of any file that imports from `@sarmal/react` when using Next.js App Router, Remix with RSC, or any other RSC-capable framework. ```tsx "use client"; import { Sarmal } from "@sarmal/react"; ``` ## `<Sarmal>` component ```tsx import { Sarmal } from "@sarmal/react"; import { curves } from "@sarmal/core"; <Sarmal curve={curves.artemis2} />; ``` The component renders a `<canvas>` element. Canvas dimensions are auto-detected from the parent container if `width`/`height` are not provided — **the parent must have an explicit height** (`height: auto` reads as 0 and triggers a 300×300 fallback with a console warning). ```tsx <Sarmal curve={curves.rose5} width={400} height={400} trailColor="#a78bfa" trailStyle="gradient-animated" onReady={(instance) => console.log("ready", instance)} /> ``` ## `<SarmalSVG>` component ```tsx import { SarmalSVG } from "@sarmal/react"; <SarmalSVG curve={curves.lissajous32} style={{ width: "200px", height: "200px" }} />; ``` SVG scales with CSS — no `width`/`height` props. Uses 0–100 viewBox units internally. ## `<SarmalDotMatrix>` component Renders the curve trail as a grid of dots on a canvas. Each dot is a rounded rectangle; `roundness` controls the corner radius from `0` (square) to `1` (circle). ```tsx import { SarmalDotMatrix } from "@sarmal/react"; import { curves } from "@sarmal/core"; <SarmalDotMatrix curve={curves.rose5} cols={40} rows={40} roundness={1} />; ``` Like `<Sarmal>`, canvas dimensions fall back to parent `clientWidth`/`clientHeight` if `width`/`height` are omitted — the parent needs an explicit height. ```tsx <SarmalDotMatrix curve={curves.artemis2} cols={32} rows={32} roundness={0.5} trailColor="#a78bfa" trailStyle="gradient-animated" onReady={(instance) => console.log("ready", instance)} /> ``` **Props not available on `<SarmalDotMatrix>`:** `headColor`, `headRadius`, `trailWidth`. Those belong to the continuous-trail canvas renderer only. ## Init props vs runtime props — most important gotcha Props are split into two categories. This applies to all three components. ### `<Sarmal>` and `<SarmalSVG>` | Category | Props | Effect when changed | | ----------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | **Runtime** | `trailColor`, `skeletonColor`, `headColor`, `trailStyle`, `trailWidth` | Updated live via `setRenderOptions` — trail is preserved | | **Init** | `trailLength`, `headRadius`, `autoStart`, `initialPhase`, `pauseOnHidden`, `width`, `height` | Destroys and recreates the instance — **trail resets** | ### `<SarmalDotMatrix>` | Category | Props | Effect when changed | | ----------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | **Runtime** | `trailColor`, `skeletonColor`, `trailStyle` | Updated live via `setRenderOptions` — trail is preserved | | **Init** | `cols`, `rows`, `roundness`, `trailLength`, `autoStart`, `initialPhase`, `pauseOnHidden`, `width`, `height` | Destroys and recreates the instance — **trail resets** | Avoid passing init props as unstable values (inline objects, computed values that change every render). Use `useMemo` or stable references if needed. ## Curve changes → automatic `morphTo` Changing the `curve` prop on any component triggers `morphTo` automatically — the trail and skeleton crossfade. Control the transition with two props: - `morphDuration` — duration in milliseconds (default 300ms) - `morphStrategy` — `"normalized"` (default) or `"raw"`. `"normalized"` maps the current phase proportionally into the new curve's period; use it when curves have different periods. `"raw"` passes the raw phase value through — can produce a jump for mismatched periods. ```tsx <Sarmal curve={activeCurve} morphDuration={500} morphStrategy="normalized" /> ``` ## Imperative access via `useSarmal` Use the hook directly when you need to call `instance.seek()`, `instance.setSpeed()`, or other imperative methods: ```tsx "use client"; import { useRef } from "react"; import { useSarmal } from "@sarmal/react"; import { curves } from "@sarmal/core"; function Loader() { const { canvasRef, instance } = useSarmal(curves.rose3); const handleClick = () => instance.current?.setSpeed(2); return <canvas ref={canvasRef} onClick={handleClick} />; } ``` `useSarmalSVG` mirrors this for SVG, returning `svgRef` instead of `canvasRef`. `useSarmalDotMatrix` mirrors this for the dot matrix, returning `canvasRef`: ```tsx "use client"; import { useSarmalDotMatrix } from "@sarmal/react"; import { curves } from "@sarmal/core"; function DotLoader() { const { canvasRef, instance } = useSarmalDotMatrix(curves.rose3); const handleClick = () => instance.current?.setSpeed(2); return <canvas ref={canvasRef} onClick={handleClick} />; } ``` ## Common mistakes - **Missing `"use client"`** — all components and hooks use `useEffect`/`useLayoutEffect`; they will error in RSC - **Parent container with no explicit height** — canvas auto-sizing reads `clientHeight`; a flex/grid parent with `height: auto` reports 0 - **Changing init props frequently** — each change destroys and recreates the instance; the trail resets visibly - **SVG `headRadius` with pixel values** — SVG space is 0–100 viewBox units, not CSS pixels - **Using `headColor`, `headRadius`, or `trailWidth` on `<SarmalDotMatrix>`** — these props only exist on the continuous-trail canvas renderer; they are not available on the dot matrix