# zriz

> zriz is an image cropper for React with a straighten dial, like the crop tool in iOS Photos. It ships as `@zriz/react` and `@zriz/core`. Every page below is Markdown, and any page URL plus `.md` returns the same.
>
> A skill for coding agents is at `https://zriz.dev/skill.md`, and an MCP server with the tools `search_docs` and `get_page` answers at `https://zriz.dev/mcp`.

## Start

- [Introduction](https://zriz.dev/docs/introduction.md): zriz is an image cropper for React with a straighten dial, like the crop tool in iOS Photos.
- [Quick start](https://zriz.dev/docs/quick-start.md): Go from an empty project to a cropper that hands you the crop.
- [Playground](https://zriz.dev/docs/playground.md): Change the main props on a live cropper and copy the code that matches what you see.

## Components

- [Root](https://zriz.dev/docs/root.md): `Root` loads the photo, keeps the crop and holds every other part.
- [Viewport](https://zriz.dev/docs/viewport.md): `Viewport` takes the gestures, `Image` draws the photo in it and `Mask` dims everything outside the crop.
- [Crop area](https://zriz.dev/docs/crop-area.md): `Area` is the crop you keep. `Handle` resizes it and `Grid` draws guides while you work.
- [Dial](https://zriz.dev/docs/dial.md): The ruler that levels a tilted photo, up to 45° each way, like the one in iOS Photos.
- [Zoom](https://zriz.dev/docs/zoom.md): A zoom slider and step buttons, for people with no wheel or pinch.
- [Aspect ratio](https://zriz.dev/docs/aspect-ratio.md): Buttons that lock the crop to a ratio such as 1:1 or 4:5, and one that swaps portrait and landscape.
- [Buttons](https://zriz.dev/docs/buttons.md): `Rotate` turns the photo a quarter turn, `Flip` mirrors it and `Reset` undoes every change.

## API

- [Value](https://zriz.dev/docs/value.md): A plain object that describes the crop. Read it to save a crop, and set it to restore or control one.
- [Events](https://zriz.dev/docs/events.md): Two callbacks on `Root` report crop changes: `onValueChange` for live UI and `onValueCommit` for saving.
- [Hooks](https://zriz.dev/docs/hooks.md): Seven hooks from `@zriz/react` that read the cropper and build parts of your own.
- [Cropper](https://zriz.dev/docs/cropper.md): `createCropper` makes the store behind every `Root`. Use it for [vanilla JS](https://zriz.dev/docs/vanilla-js.md), or to test your crop logic without a browser.

## Guides

- [Loading images](https://zriz.dev/docs/loading-images.md): Open a photo from a file input, a URL or a blob, and check which formats and sizes load.
- [Styling](https://zriz.dev/docs/styling.md): The parts carry no colour. Paint them with the optional stylesheet, your own CSS or Tailwind.
- [Composition](https://zriz.dev/docs/composition.md): Render the zriz parts as your own components, and add your own handlers next to zriz's.
- [Exporting](https://zriz.dev/docs/exporting.md): Turn the crop into an image file in the browser, or send the crop value to your server and cut the original there.
- [Accessibility](https://zriz.dev/docs/accessibility.md): zriz sets roles, keys and announcements. You write every word a screen reader says.
- [Security](https://zriz.dev/docs/security.md): What zriz handles about hostile files and private photos, and what stays your job.
- [Vanilla JS](https://zriz.dev/docs/vanilla-js.md): Run the same cropper in plain JavaScript or any framework, with `createCropper` and the DOM binders.

## Examples

- [Avatar](https://zriz.dev/docs/avatar.md): A profile photo picker: the visitor picks a file, moves it under a circle and saves a round PNG.
- [Full editor](https://zriz.dev/docs/full-editor.md): The crop area, the dial, zoom, aspect ratios, the buttons and a JPEG export in one component.
- [Server crop](https://zriz.dev/docs/server-crop.md): Send the photo and its crop value to your server, and cut the full-size original there with sharp.
- [Saving state](https://zriz.dev/docs/saving-state.md): Keep the crop for each photo in local storage and bring it back on the next visit.
- [Undo](https://zriz.dev/docs/undo.md): An undo button for the crop, built from what each commit hands you.

## Help

- [FAQ](https://zriz.dev/docs/faq.md): Short answers, each with a link to the page that covers it in full.
- [Errors](https://zriz.dev/docs/errors.md): Every error zriz throws or reports, when it happens and how to fix it.
- [Bundle size](https://zriz.dev/docs/bundle-size.md): What each set of imports adds to your bundle, minified and compressed with Brotli.
- [Changelog](https://zriz.dev/docs/changelog.md): What changed in each published version of zriz, newest first.

## Everything

- [All pages in one file](https://zriz.dev/llms-full.txt)