Image Editor

An image editor with crop, brightness, saturation, contrast, and hue adjustments, supporting rectangle and circle stencils with zoom controls.

Edit on GitHubEditllms.txt

Client Only

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-image-editor

UI Primitives(4 components)

npx shadcn@latest add button slider toggle-group tooltip

Required Packages(2 packages)

pnpm add react-advanced-cropper advanced-cropper

Usage

import { ImageEditor } from '@docyrus/ui/components/image-editor';

<ImageEditor
  src="/images/photo.jpg"
  onSave={(dataUrl) => {
    // dataUrl is a base64 canvas export
    console.log('Saved:', dataUrl);
  }}
  onUpload={(file) => {
    console.log('Uploaded:', file.name);
  }}
/>

Circle Crop with Aspect Ratio

<ImageEditor
  src="/images/avatar.jpg"
  stencilShape="circle"
  aspectRatio={1}
  onSave={handleSave}
/>

Compact Variant

<ImageEditor
  src="/images/banner.jpg"
  variant="compact"
  size="sm"
  onSave={handleSave}
/>

Variants

Variant	Description
`default`	Standard editor with full border and background.
`compact`	Reduced visual weight with subtle border and muted background.

Sizes

Size	Description
`sm`	Cropper height: 300px.
`default`	Cropper height: 400px.
`lg`	Cropper height: 500px.

API Reference

ImageEditor

Prop	Type	Default	Description
`src`	`string`	—	Initial image URL to edit.
`onSave`	`(dataUrl: string) => void`	—	Called with the base64 canvas data URL on save.
`onUpload`	`(file: File) => void`	—	Called when a new file is uploaded via the file input.
`disabled`	`boolean`	`false`	Disable all editing interactions.
`stencilShape`	`'rectangle' \| 'circle'`	`'rectangle'`	Crop area shape.
`aspectRatio`	`number`	—	Enforce a fixed aspect ratio for the crop area.
`minCropWidth`	`number`	—	Minimum crop width in pixels.
`minCropHeight`	`number`	—	Minimum crop height in pixels.
`maxCropWidth`	`number`	—	Maximum crop width in pixels.
`maxCropHeight`	`number`	—	Maximum crop height in pixels.
`variant`	`'default' \| 'compact'`	`'default'`	Visual style.
`size`	`'sm' \| 'default' \| 'lg'`	`'default'`	Cropper area height.
`className`	`string`	—	Additional CSS classes.

Type Reference

EditorMode

'crop' | 'brightness' | 'saturation' | 'contrast' | 'hue'

The active editing mode. The toolbar switches between crop and adjustment sliders based on this value.

StencilShape

'rectangle' | 'circle'

Determines the crop stencil shape. Circle mode renders a circular crop area.

Adjustments

Field	Type	Default	Description
`brightness`	`number`	`0`	Brightness adjustment (0–100 scale).
`saturation`	`number`	`0`	Saturation adjustment (0–100 scale).
`hue`	`number`	`0`	Hue rotation (0–100 scale).
`contrast`	`number`	`0`	Contrast adjustment (0–100 scale).

Editor Controls

Control	Action
Crop mode	Drag to select crop area, resize handles to adjust.
Adjustment sliders	Drag slider to adjust brightness/saturation/hue/contrast.
Zoom in/out	Buttons to zoom the image (1.25x step).
Upload	Opens file picker for a new image.
Reset	Returns to crop mode with default adjustments.
Save	Exports the cropped + adjusted result as a data URL.

Image Editor

On this page