Value

Fields

center and size are fractions of the photo after its quarter turns, never pixels. The same value fits a 400 px preview and the 4032 px original.

zriz measures each side on its own. The largest square crop of a 4032 × 3024 photo reads size: { width: 0.75, height: 1 }.

There is no zoom field. Zoom follows from size, and getZoom() returns it: 1 is the largest crop that fits.

See how zriz fixes a bad value

zriz keeps every value you set valid. It clamps the angle, reshapes a size that misses its aspect at the same area, grows a crop below minSize or past maxZoom, and shrinks or moves a crop that would show an empty corner. Ask for a 90° straighten and you get the limit:

import { createCropper } from "@zriz/core";

const cropper = createCropper({
  image: { width: 4032, height: 3024 },
});

cropper.setValue({ rotation: 90 });
cropper.getValue().rotation; // 45

A field that is not a usable number keeps the value it had, and a write with a usable field that still cannot make a crop, such as setRotation(NaN), is ignored. An aspect that is not a number from 0.000001 to 1000000 counts as "free". An option that is not a positive number falls back to its default, but any maxZoom below 1, zero and negatives included, counts as 1.

A value from zriz is frozen, so one reader cannot change it for the next. Copy it to change a field: setValue({ ...value, rotation: 2 }).

Before a photo loads, zriz stores a value as you set it and fixes it when the photo arrives.

Control the angle from React state

Pass rotation and update it in onValueChange:

"use client";

import * as Cropper from "@zriz/react/cropper";
import { useState } from "react";

export const Editor = ({ src }: { src: string }) => {
  const [rotation, setRotation] = useState(0);

  return (
    <Cropper.Root
      src={src}
      rotation={rotation}
      onValueChange={(value) => setRotation(value.rotation)}
    >
      <Cropper.Viewport style={{ maxWidth: 480, height: 360 }}>
        <Cropper.Image />
        <Cropper.Mask />
        <Cropper.Area aria-label="Crop area" />
      </Cropper.Viewport>
      <Cropper.Dial
        aria-label="Straighten"
        style={{ maxWidth: 361 }}
      >
        <Cropper.DialTicks />
      </Cropper.Dial>
    </Cropper.Root>
  );
};

rotation, zoom and aspect each control one part of the crop. A new prop moves the crop and commits, so onValueCommit runs with the whole new value. onValueChange stays quiet when each controlled prop lands as passed, even when the crop size moves with it, as it does for a new aspect. It runs when zriz applied something else: a rotation of 60 reports 45. To mirror the whole value, write it from both callbacks. A value zriz reported comes back as an answer and does not move the crop, for 2 s after the last report, so a slow store cannot rewind it. If no other answer follows and the crop has not moved since, that value applies when the 2 s end, or 500 ms after it arrived if that is later. A preset equal to a recent report lands late this way, and a value never reported lands at once. Mirror rotation, zoom or aspect from onValueChange, not onValueCommit: a store slower than 2 s that mirrors commits still flips the crop. Zoom runs from 1 up to maxZoom. A prop applied as the photo arrives is silent.

value sets the whole object without calling either callback. Each new object moves the crop, unless zriz reported that same object in the last 2 s, so keep it stable or update it from onValueChange. Reset still goes to defaultValue, not to the last value.

During a gesture and until it commits, zriz ignores a new value, rotation or zoom, so a slow render cannot fight the finger. To snap the crop after a gesture, write it in onValueCommit. A new aspect applies at once. The aspect, rotation and zoom from the first render become the reset target.

A prop acts when it changes. zoom also acts when a photo of another size arrives: with zoom={3} held, the crop goes back to 3 and commits with reason coverage. A write ignored during a gesture is not replayed. To limit a gesture, call details.cancel(). rotation={5} with no handler sets the angle once and the user can move away from it.

A photo after null counts as a first photo: zriz fits your value to it and sends nothing. Read getValue() if you keep the fitted crop.

Turn it into text and back

Save a crop as text and read it back:

import { createCropper, parse, serialize } from "@zriz/core";

const cropper = createCropper();
const text = serialize(cropper.getValue());
const saved = parse(text);

serialize adds a version field, v: 1. parse takes the text or an object you already parsed, and returns null when it is not JSON, not an object or carries a v other than 1. A value with no v still reads. It fills missing fields with defaults, clamps rotation to 45 and perspective to 30 each way, and turns a bad aspect into "free". The full flow is on saving state.

Helpers

A constant and pure functions from @zriz/core: