# React Native Skia - Animation Patterns

> Reanimated integration, path interpolation, color animation, and Atlas animation. See [SKILL.md](../SKILL.md) for decision guidance.

**Related:** [core.md](core.md) for basic shapes and canvas setup, [effects.md](effects.md) for animated shaders.

---

## Pattern 1: Shared Values as Props

Pass Reanimated shared values directly to Skia component props. No `createAnimatedComponent` needed.

```tsx
import { Canvas, Circle, RoundedRect } from "@shopify/react-native-skia";
import {
  useSharedValue,
  useDerivedValue,
  withRepeat,
  withTiming,
} from "react-native-reanimated";
import { useEffect } from "react";

const DURATION_MS = 1500;
const SIZE = 256;
const MIN_RADIUS = 10;
const MAX_RADIUS = 80;

export function AnimatedShapes() {
  const progress = useSharedValue(0);

  useEffect(() => {
    progress.value = withRepeat(
      withTiming(1, { duration: DURATION_MS }),
      -1,
      true,
    );
  }, []);

  // Derive values from the animated progress
  const radius = useDerivedValue(
    () => MIN_RADIUS + progress.value * (MAX_RADIUS - MIN_RADIUS),
  );
  const x = useDerivedValue(() => progress.value * (SIZE - MAX_RADIUS * 2));

  return (
    <Canvas style={{ width: SIZE, height: SIZE }}>
      <Circle cx={128} cy={80} r={radius} color="cyan" />
      <RoundedRect x={x} y={150} width={60} height={60} r={8} color="orange" />
    </Canvas>
  );
}
```

**Why good:** `radius` and `x` are derived values that update on UI thread, zero JS bridge cost, 60 FPS guaranteed

```tsx
// BAD: Using createAnimatedComponent (unnecessary with Skia)
import Animated from "react-native-reanimated";
const AnimatedCircle = Animated.createAnimatedComponent(Circle); // WRONG
```

**Why bad:** Skia components natively accept shared values -- wrapping in Animated adds overhead and complexity for no benefit

---

## Pattern 2: Color Animation with interpolateColors

Skia uses a different internal color format than Reanimated. Always use `interpolateColors` from Skia.

```tsx
import { Canvas, Circle, interpolateColors } from "@shopify/react-native-skia";
import {
  useSharedValue,
  useDerivedValue,
  withRepeat,
  withTiming,
} from "react-native-reanimated";
import { useEffect } from "react";

const CYCLE_DURATION = 3000;
const COLORS = ["cyan", "magenta", "yellow", "cyan"];
const COLOR_STOPS = [0, 0.33, 0.66, 1];

export function ColorCycleCircle() {
  const progress = useSharedValue(0);

  useEffect(() => {
    progress.value = withRepeat(
      withTiming(1, { duration: CYCLE_DURATION }),
      -1,
    );
  }, []);

  const color = useDerivedValue(() =>
    interpolateColors(progress.value, COLOR_STOPS, COLORS),
  );

  return (
    <Canvas style={{ width: 200, height: 200 }}>
      <Circle cx={100} cy={100} r={60} color={color} />
    </Canvas>
  );
}
```

**Why good:** `interpolateColors` from Skia handles Skia's internal color format correctly

```tsx
// BAD: Using Reanimated's interpolateColor
import { interpolateColor } from "react-native-reanimated"; // WRONG for Skia
const color = useDerivedValue(() =>
  interpolateColor(progress.value, [0, 1], ["red", "blue"]),
);
```

**Why bad:** Reanimated's `interpolateColor` uses a different internal format, produces wrong/flickering colors in Skia components

---

## Pattern 3: Path Interpolation

Morph between multiple paths smoothly. Paths must have the same number and types of commands.

```tsx
import { Canvas, Path, usePathInterpolation } from "@shopify/react-native-skia";
import {
  useSharedValue,
  withRepeat,
  withTiming,
} from "react-native-reanimated";
import { useEffect } from "react";

const MORPH_DURATION = 2000;

// All paths must have identical command structure (same moveTo, lineTo, etc. count)
const TRIANGLE = "M 128 20 L 236 200 L 20 200 Z";
const DIAMOND = "M 128 20 L 236 128 L 128 236 Z";
const SQUARE = "M 40 40 L 216 40 L 216 216 Z";

export function MorphingShape() {
  const progress = useSharedValue(0);

  useEffect(() => {
    progress.value = withRepeat(
      withTiming(1, { duration: MORPH_DURATION }),
      -1,
      true,
    );
  }, []);

  const path = usePathInterpolation(
    progress,
    [0, 0.5, 1],
    [TRIANGLE, DIAMOND, SQUARE],
  );

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Path path={path} color="purple" />
    </Canvas>
  );
}
```

**Why good:** `usePathInterpolation` handles the interpolation on UI thread, multiple keyframes supported

**Gotcha:** paths with different command counts crash at runtime. For incompatible paths, preprocess with a library like Flubber.

---

## Pattern 4: Dynamic Paths with usePathValue

For paths that change shape every frame (e.g., waveforms, trails), use `usePathValue` with a worklet callback.

```tsx
import { Canvas, Path, usePathValue, Skia } from "@shopify/react-native-skia";
import { useClock } from "@shopify/react-native-skia";

const WAVE_POINTS = 50;
const AMPLITUDE = 30;
const CANVAS_WIDTH = 300;
const CANVAS_HEIGHT = 200;

export function AnimatedWave() {
  const clock = useClock();

  const path = usePathValue((cPath) => {
    "worklet";
    const t = clock.value / 1000;
    cPath.reset();
    cPath.moveTo(0, CANVAS_HEIGHT / 2);

    for (let i = 0; i <= WAVE_POINTS; i++) {
      const x = (i / WAVE_POINTS) * CANVAS_WIDTH;
      const y = CANVAS_HEIGHT / 2 + Math.sin(x * 0.05 + t * 3) * AMPLITUDE;
      cPath.lineTo(x, y);
    }
  });

  return (
    <Canvas style={{ width: CANVAS_WIDTH, height: CANVAS_HEIGHT }}>
      <Path path={path} color="teal" style="stroke" strokeWidth={2} />
    </Canvas>
  );
}
```

**Why good:** worklet runs on UI thread, path updated every frame without JS thread involvement, `useClock` provides elapsed time

---

## Pattern 5: Animated Atlas with useRSXformBuffer

Animate thousands of sprites with worklet-based transforms at near-zero cost.

```tsx
import {
  Canvas,
  Atlas,
  useImage,
  rect,
  useRSXformBuffer,
} from "@shopify/react-native-skia";
import { useClock } from "@shopify/react-native-skia";

const SPRITE_COUNT = 100;
const SPRITE_SIZE = 16;
const CANVAS_SIZE = 256;

export function AnimatedSprites() {
  const texture = useImage(require("./particle.png"));
  const clock = useClock();

  const sprites = Array.from({ length: SPRITE_COUNT }, () =>
    rect(0, 0, SPRITE_SIZE, SPRITE_SIZE),
  );

  const transforms = useRSXformBuffer(SPRITE_COUNT, (val, i) => {
    "worklet";
    const t = clock.value / 1000;
    const angle = (i / SPRITE_COUNT) * Math.PI * 2 + t;
    const radius = 60 + Math.sin(t + i * 0.1) * 30;
    const x = CANVAS_SIZE / 2 + Math.cos(angle) * radius;
    const y = CANVAS_SIZE / 2 + Math.sin(angle) * radius;
    const scale = 0.5 + Math.sin(t * 2 + i) * 0.3;

    val.set(Math.cos(angle) * scale, Math.sin(angle) * scale, x, y);
  });

  if (!texture) return null;

  return (
    <Canvas style={{ width: CANVAS_SIZE, height: CANVAS_SIZE }}>
      <Atlas image={texture} sprites={sprites} transforms={transforms} />
    </Canvas>
  );
}
```

**Why good:** `useRSXformBuffer` runs worklet per sprite per frame on UI thread, single draw call for all 100 sprites, `val.set(scos, ssin, tx, ty)` is the RSXform interface

# React Native Skia - Core Patterns

> Canvas setup, shapes, paths, paint, groups, and images. See [SKILL.md](../SKILL.md) for decision guidance and red flags.

**Prerequisites:** Familiarity with React Native and basic 2D graphics concepts.

---

## Pattern 1: Canvas with Reactive Sizing

```tsx
import { Canvas, Circle, useCanvasSize } from "@shopify/react-native-skia";
import { useSharedValue } from "react-native-reanimated";
import type { SharedValue } from "react-native-reanimated";

// onSize: UI thread reactive dimensions (preferred for animations)
export function ReactiveCanvas() {
  const size = useSharedValue({ width: 0, height: 0 });

  return (
    <Canvas style={{ flex: 1 }} onSize={size}>
      <CenteredCircle size={size} />
    </Canvas>
  );
}

// useCanvasSize: JS thread dimensions (for layout calculations)
function CenteredCircle({
  size,
}: {
  size: SharedValue<{ width: number; height: number }>;
}) {
  // Derive center from shared value for UI thread animation
  return <Circle cx={128} cy={128} r={40} color="cyan" />;
}
```

**Why good:** `onSize` updates on UI thread without JS bridge, `useCanvasSize` available for JS-thread calculations

---

## Pattern 2: All Shape Primitives

```tsx
import {
  Canvas,
  Circle,
  Rect,
  RoundedRect,
  Line,
  Oval,
  Points,
  DiffRect,
  rrect,
  rect,
} from "@shopify/react-native-skia";

const CANVAS_SIZE = 300;
const CORNER_RADIUS = 12;
const STROKE_WIDTH = 2;

export function ShapeShowcase() {
  return (
    <Canvas style={{ width: CANVAS_SIZE, height: CANVAS_SIZE }}>
      {/* Filled shapes */}
      <Circle cx={50} cy={50} r={30} color="cyan" />
      <Rect x={100} y={20} width={60} height={60} color="red" />
      <RoundedRect
        x={180}
        y={20}
        width={60}
        height={60}
        r={CORNER_RADIUS}
        color="blue"
      />
      <Oval x={20} y={100} width={80} height={50} color="green" />

      {/* Stroked shapes */}
      <Circle
        cx={180}
        cy={130}
        r={30}
        color="purple"
        style="stroke"
        strokeWidth={STROKE_WIDTH}
      />
      <Line
        p1={{ x: 0, y: 200 }}
        p2={{ x: 300, y: 200 }}
        color="gray"
        strokeWidth={1}
      />

      {/* Points */}
      <Points
        points={[
          { x: 50, y: 250 },
          { x: 100, y: 230 },
          { x: 150, y: 260 },
        ]}
        mode="polygon"
        color="orange"
        style="stroke"
        strokeWidth={STROKE_WIDTH}
      />

      {/* DiffRect: outer rect minus inner rect (ring/frame shape) */}
      <DiffRect
        outer={rrect(rect(180, 200, 80, 80), CORNER_RADIUS, CORNER_RADIUS)}
        inner={rrect(rect(195, 215, 50, 50), 8, 8)}
        color="pink"
      />
    </Canvas>
  );
}
```

---

## Pattern 3: Path Operations

```tsx
import { Canvas, Path, DashPathEffect, Skia } from "@shopify/react-native-skia";

const STROKE_WIDTH = 3;

// Declarative: SVG path string
export function DeclarativePath() {
  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Path
        path="M 10 80 Q 95 10 180 80 T 350 80"
        color="purple"
        style="stroke"
        strokeWidth={STROKE_WIDTH}
        strokeCap="round"
      />
    </Canvas>
  );
}

// Imperative: dynamic construction
export function ImperativePath() {
  const path = Skia.Path.Make();
  path.moveTo(10, 80);
  path.quadTo(95, 10, 180, 80);
  path.cubicTo(200, 120, 250, 50, 300, 80);
  path.close();

  return (
    <Canvas style={{ width: 320, height: 160 }}>
      <Path path={path} color="teal" />
    </Canvas>
  );
}

// Path with dash effect
export function DashedPath() {
  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Path
        path="M 10 128 L 246 128"
        color="black"
        style="stroke"
        strokeWidth={2}
      >
        {/* DashPathEffect: [dashLength, gapLength] */}
        <DashPathEffect intervals={[10, 5]} />
      </Path>
    </Canvas>
  );
}
```

**Why good:** declarative SVG strings for static paths, imperative API for data-driven shapes, path effects compose as children

---

## Pattern 4: Paint Composition (Multiple Fills/Strokes)

A single shape can have multiple paint layers by adding `<Paint>` children. This creates effects like fill + stroke, or fill + inner shadow.

```tsx
import { Canvas, Circle, Paint } from "@shopify/react-native-skia";

const OUTER_STROKE = 3;

export function MultiPaintCircle() {
  return (
    <Canvas style={{ width: 200, height: 200 }}>
      <Circle cx={100} cy={100} r={60}>
        {/* First paint: blue fill */}
        <Paint color="blue" />
        {/* Second paint: white stroke on top */}
        <Paint color="white" style="stroke" strokeWidth={OUTER_STROKE} />
      </Circle>
    </Canvas>
  );
}
```

**Why good:** multiple paints on one shape without duplicating the shape, paints render in order (fill first, then stroke)

---

## Pattern 5: Group Transforms and Clipping

```tsx
import { Canvas, Group, Rect, Circle, Skia } from "@shopify/react-native-skia";

const ROTATION_DEGREES = 45;
const ROTATION_RADIANS = (ROTATION_DEGREES * Math.PI) / 180;

// Transform with explicit origin (default is top-left, NOT center)
export function RotatedGroup() {
  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Group
        transform={[{ rotate: ROTATION_RADIANS }]}
        origin={{ x: 128, y: 128 }}
      >
        <Rect x={88} y={88} width={80} height={80} color="red" />
      </Group>
    </Canvas>
  );
}

// Clipping with a path
export function ClippedGroup() {
  const clipPath = Skia.Path.Make();
  clipPath.addCircle(128, 128, 80);

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Group clip={clipPath}>
        <Rect x={0} y={0} width={256} height={256} color="blue" />
        {/* Only the portion inside the circle clip is visible */}
      </Group>
    </Canvas>
  );
}

// Inverted clip: show everything OUTSIDE the clip region
export function InvertedClip() {
  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Group clip={{ x: 80, y: 80, width: 96, height: 96 }} invertClip>
        <Rect x={0} y={0} width={256} height={256} color="green" />
      </Group>
    </Canvas>
  );
}
```

**Why good:** explicit origin prevents rotation surprise (default top-left), clip accepts rect/rrect/path, invertClip for masking effects

---

## Pattern 6: Images and FitBox

```tsx
import {
  Canvas,
  Image,
  useImage,
  FitBox,
  Circle,
  rect,
} from "@shopify/react-native-skia";

export function ImageExample() {
  const image = useImage(require("./photo.png"));
  if (!image) return null; // Always guard: useImage returns null while loading

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      {/* fit modes: contain, cover, fill, fitWidth, fitHeight, none */}
      <Image image={image} x={0} y={0} width={256} height={256} fit="cover" />
    </Canvas>
  );
}

// FitBox: auto-scale content to fit a destination rectangle
export function FitBoxExample() {
  const SRC = rect(0, 0, 100, 100); // Original coordinate space
  const DST = rect(0, 0, 256, 256); // Target display size

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <FitBox src={SRC} dst={DST} fit="contain">
        {/* These coordinates are in the 100x100 source space */}
        <Circle cx={50} cy={50} r={40} color="cyan" />
      </FitBox>
    </Canvas>
  );
}
```

**Why good:** FitBox auto-scales children from source to destination coordinates, image `fit` modes match React Native Image behavior

---

## Pattern 7: Layer Property for Non-Standard Components

Paragraph, Picture, and ImageSVG do not inherit paint from parent Groups. Use the `layer` property to apply effects.

```tsx
import { Canvas, Group, Paragraph, Paint, Blur } from "@shopify/react-native-skia";

// BAD: Blur on Group does NOT apply to Paragraph
<Group>
  <Blur blur={4} />
  <Paragraph paragraph={para} x={0} y={0} width={300} />
</Group>

// GOOD: Use layer property
<Group layer={<Paint><Blur blur={4} /></Paint>}>
  <Paragraph paragraph={para} x={0} y={0} width={300} />
</Group>
```

**Why bad:** Paragraph ignores paint children on parent Group, blur silently has no effect

**Why good:** `layer` creates a bitmap rendering layer, effects apply to the entire group output including Paragraph

# React Native Skia - Effects Patterns

> Image filters, backdrop blur, shaders, and RuntimeShader. See [SKILL.md](../SKILL.md) for decision guidance.

**Related:** [core.md](core.md) for shapes and paint, [animations.md](animations.md) for animating shader uniforms.

---

## Pattern 1: Image Filters (Blur, Shadow, ColorMatrix)

Image filters compose as children of shapes or Groups. Multiple filters can be nested.

```tsx
import {
  Canvas,
  Image,
  Rect,
  Blur,
  Shadow,
  ColorMatrix,
  useImage,
} from "@shopify/react-native-skia";

const BLUR_SIGMA = 8;
const SHADOW_DX = 4;
const SHADOW_DY = 4;
const SHADOW_BLUR = 6;

// Blur filter
export function BlurredImage() {
  const image = useImage(require("./photo.png"));
  if (!image) return null;

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Image image={image} fit="cover" x={0} y={0} width={256} height={256}>
        <Blur blur={BLUR_SIGMA} mode="clamp" />
      </Image>
    </Canvas>
  );
}

// Shadow filter
export function ShadowedRect() {
  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Rect x={40} y={40} width={160} height={160} color="white">
        <Shadow
          dx={SHADOW_DX}
          dy={SHADOW_DY}
          blur={SHADOW_BLUR}
          color="rgba(0,0,0,0.4)"
        />
      </Rect>
    </Canvas>
  );
}

// Composed: Blur + ColorMatrix (grayscale)
const GRAYSCALE_MATRIX = [
  0.2126, 0.7152, 0.0722, 0, 0, 0.2126, 0.7152, 0.0722, 0, 0, 0.2126, 0.7152,
  0.0722, 0, 0, 0, 0, 0, 1, 0,
];

export function GrayscaleBlurredImage() {
  const image = useImage(require("./photo.png"));
  if (!image) return null;

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Image image={image} fit="cover" x={0} y={0} width={256} height={256}>
        <Blur blur={4} mode="clamp">
          <ColorMatrix matrix={GRAYSCALE_MATRIX} />
        </Blur>
      </Image>
    </Canvas>
  );
}
```

**Why good:** filters compose by nesting (inner applied first), Blur `mode` controls edge behavior ("clamp", "repeat", "mirror", "decal")

---

## Pattern 2: Backdrop Blur and Backdrop Filter

Apply effects to content behind a clipping region (like CSS `backdrop-filter`). BackdropBlur is a convenience wrapper; BackdropFilter accepts any image filter child.

```tsx
import {
  Canvas,
  Image,
  BackdropBlur,
  BackdropFilter,
  Fill,
  ColorMatrix,
  useImage,
} from "@shopify/react-native-skia";

const BACKDROP_BLUR_RADIUS = 10;

export function GlassMorphism() {
  const image = useImage(require("./background.png"));
  if (!image) return null;

  return (
    <Canvas style={{ width: 300, height: 400 }}>
      {/* Background image */}
      <Image image={image} fit="cover" x={0} y={0} width={300} height={400} />

      {/* Frosted glass panel in bottom half */}
      <BackdropBlur
        blur={BACKDROP_BLUR_RADIUS}
        clip={{ x: 20, y: 200, width: 260, height: 180 }}
      >
        <Fill color="rgba(255, 255, 255, 0.2)" />
      </BackdropBlur>
    </Canvas>
  );
}

// BackdropFilter with custom ColorMatrix
const SEPIA_MATRIX = [
  0.393, 0.769, 0.189, 0, 0, 0.349, 0.686, 0.168, 0, 0, 0.272, 0.534, 0.131, 0,
  0, 0, 0, 0, 1, 0,
];

export function SepiaBackdrop() {
  return (
    <Canvas style={{ width: 256, height: 256 }}>
      {/* Content behind the filter */}
      <Fill color="cyan" />

      {/* Apply sepia to bottom half */}
      <BackdropFilter clip={{ x: 0, y: 128, width: 256, height: 128 }}>
        <ColorMatrix matrix={SEPIA_MATRIX} />
      </BackdropFilter>
    </Canvas>
  );
}
```

**Why good:** BackdropBlur/BackdropFilter apply to content already drawn on canvas (behind the clip), not to their own children

---

## Pattern 3: Custom SkSL Shader

Write GPU shaders with `Skia.RuntimeEffect.Make()`. Uniforms are passed as a plain object. Animate uniforms with shared values.

```tsx
import { Canvas, Fill, Shader, Skia } from "@shopify/react-native-skia";
import {
  useSharedValue,
  useDerivedValue,
  withRepeat,
  withTiming,
} from "react-native-reanimated";
import { useEffect } from "react";

const ANIMATION_DURATION = 4000;
const CANVAS_SIZE = 256;

const GRADIENT_SHADER = `
  uniform float2 iResolution;
  uniform float iTime;

  vec4 main(vec2 pos) {
    vec2 uv = pos / iResolution;
    float r = 0.5 + 0.5 * sin(iTime + uv.x * 6.28);
    float g = 0.5 + 0.5 * sin(iTime * 1.3 + uv.y * 6.28);
    float b = 0.5 + 0.5 * sin(iTime * 0.7 + (uv.x + uv.y) * 3.14);
    return vec4(r, g, b, 1.0);
  }
`;

const effect = Skia.RuntimeEffect.Make(GRADIENT_SHADER);

export function AnimatedGradientShader() {
  const time = useSharedValue(0);

  useEffect(() => {
    time.value = withRepeat(
      withTiming(6.28, { duration: ANIMATION_DURATION }),
      -1,
    );
  }, []);

  if (!effect) return null; // Shader compilation failed

  return (
    <Canvas style={{ width: CANVAS_SIZE, height: CANVAS_SIZE }}>
      <Fill>
        <Shader
          source={effect}
          uniforms={{ iResolution: [CANVAS_SIZE, CANVAS_SIZE], iTime: time }}
        />
      </Fill>
    </Canvas>
  );
}
```

**Why good:** uniforms accept shared values directly for animation, `iResolution` as `float2` matches SkSL's `uniform float2`, null check handles shader compilation errors

---

## Pattern 4: RuntimeShader as Image Filter

RuntimeShader processes existing canvas content as a shader uniform. The filtered image is available as `uniform shader image` implicitly.

```tsx
import {
  Canvas,
  Image,
  RuntimeShader,
  Skia,
  useImage,
} from "@shopify/react-native-skia";

const PIXELATE_SHADER = `
  uniform shader image;
  uniform float2 resolution;
  uniform float pixelSize;

  vec4 main(vec2 pos) {
    vec2 uv = pos / resolution;
    vec2 blockUV = floor(uv * pixelSize) / pixelSize;
    return image.eval(blockUV * resolution);
  }
`;

const pixelateEffect = Skia.RuntimeEffect.Make(PIXELATE_SHADER);

const PIXEL_COUNT = 32;
const CANVAS_SIZE = 256;

export function PixelatedImage() {
  const photo = useImage(require("./photo.png"));
  if (!photo || !pixelateEffect) return null;

  return (
    <Canvas style={{ width: CANVAS_SIZE, height: CANVAS_SIZE }}>
      <Image
        image={photo}
        fit="cover"
        x={0}
        y={0}
        width={CANVAS_SIZE}
        height={CANVAS_SIZE}
      >
        <RuntimeShader
          source={pixelateEffect}
          uniforms={{
            resolution: [CANVAS_SIZE, CANVAS_SIZE],
            pixelSize: PIXEL_COUNT,
          }}
        />
      </Image>
    </Canvas>
  );
}
```

**Why good:** `image.eval(xy)` samples the source image at given coordinates, uniforms control the effect parameters

**Gotcha:** RuntimeShader does not account for pixel density scaling. On high-DPI screens, content appears blurry. Fix by wrapping in a Group with `transform={[{ scale: pd }]}` and rendering into a canvas scaled by `1/pd`.

---

## Pattern 5: Shader with Child Shaders

Compose shaders by declaring `uniform shader` and sampling with `.eval(xy)`.

```tsx
import {
  Canvas,
  Fill,
  Shader,
  ImageShader,
  Skia,
  useImage,
} from "@shopify/react-native-skia";

const SWIRL_SHADER = `
  uniform shader image;
  uniform float2 center;
  uniform float radius;
  uniform float angle;

  vec4 main(vec2 pos) {
    vec2 d = pos - center;
    float dist = length(d);
    if (dist < radius) {
      float percent = (radius - dist) / radius;
      float theta = percent * percent * angle;
      float cosT = cos(theta);
      float sinT = sin(theta);
      d = vec2(d.x * cosT - d.y * sinT, d.x * sinT + d.y * cosT);
    }
    return image.eval(d + center);
  }
`;

const swirlEffect = Skia.RuntimeEffect.Make(SWIRL_SHADER);
const SWIRL_ANGLE = 3.14;
const SWIRL_RADIUS = 100;

export function SwirlImage() {
  const photo = useImage(require("./photo.png"));
  if (!photo || !swirlEffect) return null;

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      <Fill>
        <Shader
          source={swirlEffect}
          uniforms={{
            center: [128, 128],
            radius: SWIRL_RADIUS,
            angle: SWIRL_ANGLE,
          }}
        >
          {/* Child shader: image texture available as `uniform shader image` */}
          <ImageShader
            image={photo}
            fit="cover"
            x={0}
            y={0}
            width={256}
            height={256}
          />
        </Shader>
      </Fill>
    </Canvas>
  );
}
```

**Why good:** child shader automatically binds to the first `uniform shader` declaration, `.eval(xy)` samples the child at computed coordinates, enables complex image distortion effects

# React Native Skia - Text and Media Patterns

> Paragraph API, SVG rendering, Picture recording, and offscreen rendering. See [SKILL.md](../SKILL.md) for decision guidance.

**Related:** [core.md](core.md) for basic shapes, [effects.md](effects.md) for applying effects to Paragraphs via `layer`.

---

## Pattern 1: Paragraph with Mixed Styles

The Paragraph API handles rich text with multiple fonts, weights, and alignment. Build paragraphs with `ParagraphBuilder`.

```tsx
import {
  Canvas,
  Paragraph,
  Skia,
  useFonts,
  TextAlign,
  FontStyle,
} from "@shopify/react-native-skia";

const PARAGRAPH_WIDTH = 280;
const TITLE_SIZE = 28;
const BODY_SIZE = 16;
const LINE_HEIGHT_MULTIPLIER = 1.5;

export function RichTextParagraph() {
  const fonts = useFonts({
    Roboto: [
      require("./fonts/Roboto-Regular.ttf"),
      require("./fonts/Roboto-Bold.ttf"),
      require("./fonts/Roboto-Italic.ttf"),
    ],
  });

  if (!fonts) return null; // Fonts loading -- always guard

  const paraStyle = {
    textAlign: TextAlign.Left,
    maxLines: 10,
    ellipsis: "...",
  };

  const para = Skia.ParagraphBuilder.Make(paraStyle, fonts)
    .pushStyle({
      fontSize: TITLE_SIZE,
      fontFamilies: ["Roboto"],
      fontStyle: FontStyle.Bold,
      color: Skia.Color("black"),
    })
    .addText("Welcome to Skia\n")
    .pop()
    .pushStyle({
      fontSize: BODY_SIZE,
      fontFamilies: ["Roboto"],
      color: Skia.Color("#444"),
      heightMultiplier: LINE_HEIGHT_MULTIPLIER,
    })
    .addText("React Native Skia provides a ")
    .pushStyle({
      fontSize: BODY_SIZE,
      fontFamilies: ["Roboto"],
      fontStyle: FontStyle.Italic,
      color: Skia.Color("#444"),
    })
    .addText("powerful")
    .pop()
    .addText(
      " Paragraph API for rich text layout with automatic line breaking.",
    )
    .pop()
    .build();

  para.layout(PARAGRAPH_WIDTH);

  return (
    <Canvas style={{ width: PARAGRAPH_WIDTH, height: para.getHeight() + 20 }}>
      <Paragraph paragraph={para} x={0} y={10} width={PARAGRAPH_WIDTH} />
    </Canvas>
  );
}
```

**Why good:** mixed bold/italic/regular in one text block, automatic line breaking, measurable height for dynamic canvas sizing

**Key methods after `build()`:**

- `para.layout(width)` -- compute layout for given width (must call before rendering)
- `para.getHeight()` -- total paragraph height after layout
- `para.getLongestLine()` -- width of the longest line (useful for centering)

---

## Pattern 2: SVG Rendering

Render SVG files or strings with the `ImageSVG` component. SVGs use Skia's SVG module and have specific limitations.

```tsx
import { Canvas, ImageSVG, useSVG, Skia } from "@shopify/react-native-skia";

// From file
export function SVGFromFile() {
  const svg = useSVG(require("./icon.svg"));
  if (!svg) return null; // Loading -- always guard

  return (
    <Canvas style={{ width: 200, height: 200 }}>
      <ImageSVG svg={svg} x={0} y={0} width={200} height={200} />
    </Canvas>
  );
}

// From string
export function SVGFromString() {
  const svg = Skia.SVG.MakeFromString(`
    <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
      <circle cx="50" cy="50" r="40" fill="coral" />
      <rect x="30" y="30" width="40" height="40" fill="white" opacity="0.5" />
    </svg>
  `);

  if (!svg) return null;

  return (
    <Canvas style={{ width: 200, height: 200 }}>
      <ImageSVG svg={svg} x={0} y={0} width={200} height={200} />
    </Canvas>
  );
}
```

**SVG limitations (not supported):**

- `<text>` elements
- CSS styles (preprocess with SVGO to convert to attributes)
- RGBA color syntax (use `rgb()` + `fill-opacity`/`stroke-opacity`)
- `<animate>`, `<foreignObject>`, `<script>`, `<view>`
- Gradient `xlink:href` (deprecated)

**Why good:** `useSVG` handles async loading, `Skia.SVG.MakeFromString` for inline SVGs

---

## Pattern 3: Picture Recording

Pictures record drawing operations and replay them. Useful for dynamic draw counts (e.g., trails, particle effects) and sharing drawings between canvases.

```tsx
import {
  Canvas,
  Picture,
  Skia,
  Group,
  Paint,
  Blur,
} from "@shopify/react-native-skia";

const TRAIL_LENGTH = 20;
const TRAIL_RADIUS = 5;

// Record dynamic number of drawing operations
export function TrailEffect({
  points,
}: {
  points: Array<{ x: number; y: number }>;
}) {
  const recorder = Skia.PictureRecorder();
  const canvas = recorder.beginRecording({
    x: 0,
    y: 0,
    width: 256,
    height: 256,
  });

  // Draw variable number of circles (can't do this with JSX without changing component count)
  const visiblePoints = points.slice(-TRAIL_LENGTH);
  visiblePoints.forEach((point, i) => {
    const opacity = (i + 1) / visiblePoints.length;
    const paint = Skia.Paint();
    paint.setColor(Skia.Color(`rgba(0, 200, 255, ${opacity})`));
    canvas.drawCircle(point.x, point.y, TRAIL_RADIUS, paint);
  });

  const picture = recorder.finishRecordingAsPicture();

  return (
    <Canvas style={{ width: 256, height: 256 }}>
      {/* Apply effects via layer since Picture doesn't inherit paint */}
      <Group
        layer={
          <Paint>
            <Blur blur={2} />
          </Paint>
        }
      >
        <Picture picture={picture} />
      </Group>
    </Canvas>
  );
}
```

**When to use Picture:**

- Variable number of draw operations per frame (trails, particles)
- Reusing the same drawing in multiple locations
- Immediate-mode drawing with imperative Skia API
- Serializing drawings for debugging (`picture.serialize()`)

**Why good:** Picture operates in immediate mode (variable draw count), immutable after recording (safe to share), can be serialized for debugging

---

## Pattern 4: Canvas Snapshots

Capture canvas content as an image for sharing, saving, or processing.

```tsx
import {
  Canvas,
  Circle,
  Rect,
  type SkiaView,
} from "@shopify/react-native-skia";
import { useRef, useCallback } from "react";

export function SnapshotExample() {
  const canvasRef = useRef<SkiaView>(null);

  const captureSnapshot = useCallback(async () => {
    if (!canvasRef.current) return;

    // Use async version for drawings that include images/textures
    const image = await canvasRef.current.makeImageSnapshotAsync();
    if (!image) return;

    // Convert to base64 for sharing
    const data = image.encodeToBase64();
    // Use data as needed (save, share, upload)
  }, []);

  return (
    <Canvas ref={canvasRef} style={{ width: 256, height: 256 }}>
      <Rect x={0} y={0} width={256} height={256} color="white" />
      <Circle cx={128} cy={128} r={60} color="blue" />
    </Canvas>
  );
}
```

**Key distinction:**

- `makeImageSnapshotAsync()` -- use when canvas has images, shaders, or textures (promise-based)
- `makeImageSnapshot(rect?)` -- use for texture-free drawings (synchronous, optional crop rect)

---

## Pattern 5: Offscreen Rendering (Headless)

Generate images without displaying a Canvas. Useful for thumbnails, export, or server-side rendering.

```tsx
import {
  LoadSkiaWeb,
  makeOffscreenSurface,
  drawOffscreen,
} from "@shopify/react-native-skia/lib/commonjs/headless";
import { Circle, Fill } from "@shopify/react-native-skia";

const SURFACE_WIDTH = 512;
const SURFACE_HEIGHT = 512;

export async function generateThumbnail(): Promise<string> {
  // 1. Initialize CanvasKit (required for headless)
  await LoadSkiaWeb();

  // 2. Create offscreen surface
  const surface = makeOffscreenSurface(SURFACE_WIDTH, SURFACE_HEIGHT);

  // 3. Draw using React Native Skia components
  const image = drawOffscreen(
    surface,
    <>
      <Fill color="white" />
      <Circle cx={256} cy={256} r={120} color="blue" />
    </>,
  );

  // 4. Encode to base64
  return image.encodeToBase64();
}
```

**When to use offscreen rendering:**

- Generating thumbnails or previews without a visible Canvas
- Server-side image generation (Node.js with CanvasKit)
- Pre-rendering complex scenes for later display

**Import path:** headless mode requires CommonJS imports: `@shopify/react-native-skia/lib/commonjs/headless`