@sarmal/react

@sarmal/react gives you a <Sarmal> component and a useSarmal hook so you can drop parametric curve animations into React apps without the canvas wiring. SVG output is also supported with <SarmalSVG> and useSarmalSVG.

Install

npm install @sarmal/react @sarmal/core

Quick Start

import { Sarmal } from "@sarmal/react";
import { rose3 } from "@sarmal/core";

export function Loader() {
  return <Sarmal curve={rose3} width={200} height={200} />;
}

That's it. The canvas is created, the animation starts, and everything is cleaned up when the component unmounts.

Canvas sizing

The canvas buffer dimensions must match the display size, otherwise the sarmal will distorted. Pass width and height props directly, or wrap the component in a container with explicit dimensions:

// Pass dimensions directly
<Sarmal curve={rose5} width={200} height={200} />

// Or provide a sized parent
<div style={{ width: 200, height: 200 }}>
  <Sarmal curve={rose5} />
</div>

Important: The parent container must have an explicit height. height: auto will result in clientHeight = 0 and a 300x300 fallback canvas with a console warning. width and height are set during initialization, so changing them after mount destroys and recreates the instance (trail resets).

Changing the curve

Pass a different curve prop and the component will morph to it smoothly. Control the duration with morphDuration (ms):

const [curve, setCurve] = useState(rose3);

<Sarmal curve={curve} morphDuration={600} width={200} height={200} />;

Styling

<Sarmal
  curve={rose5}
  trailColor="#00ffaa"
  skeletonColor="transparent"
  headColor="#ffffff"
  trailStyle="gradient-animated"
  trailWidth={1.5}
  width={200}
  height={200}
/>

trailColor accepts a single hex string or an array for gradients:

trailColor={["#ff0080", "#7928ca", "#0070f3"]}

Props

See sarmal.art/docs/api for the full props reference.

SVG output

The <SarmalSVG> component and useSarmalSVG hook render to SVG instead of canvas. The API mirrors <Sarmal> and useSarmal, with these differences:

• SVG elements scale naturally with CSS, so no width/height sizing props needed. A viewBox="0 0 100 100" is set automatically.
• className and style apply to the <svg> element.
• trailLength and headRadius are still available as init-time props.

<SarmalSVG> component

import { SarmalSVG } from "@sarmal/react";
import { rose3 } from "@sarmal/core";

export function Loader() {
  return <SarmalSVG curve={rose3} style={{ width: 200, height: 200 }} />;
}

useSarmalSVG hook

import { useSarmalSVG } from "@sarmal/react";
import { rose5 } from "@sarmal/core";

function MyComponent() {
  const { svgRef, instance } = useSarmalSVG(rose5);

  return (
    <>
      <svg ref={svgRef} />
      <button onClick={() => instance.current?.pause()}>Pause</button>
      <button onClick={() => instance.current?.play()}>Play</button>
    </>
  );
}

The hook returns:

• svgRef: attach this to your <svg> element
• instance: a ref to the live SarmalInstance

useSarmal hook

If you need direct access to the SarmalInstance (to call play, pause, seek, etc.), use the hook:

import { useSarmal } from "@sarmal/react";
import { rose5 } from "@sarmal/core";

function MyComponent() {
  const { canvasRef, instance } = useSarmal(rose5, undefined, { width: 200, height: 200 });

  return (
    <>
      <canvas ref={canvasRef} />
      <button onClick={() => instance.current?.pause()}>Pause</button>
      <button onClick={() => instance.current?.play()}>Play</button>
    </>
  );
}

The hook returns:

• canvasRef: attach this to your <canvas> element
• instance: a ref to the live SarmalInstance

Documentation

Full API reference and examples are at sarmal.art/docs

License

MIT © Alper Halil

Links

• Homepage: See everything Sarmal has to offer
• Core package: The engine behind this one
• npm: Package registry