# Image Editor
URL: /docs/web/components/image-editor

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

**Demo:**

```tsx
'use client';
// @custom-demo

import { useCallback, useState } from 'react';

// next/image removed — using native <img> in Vite

import { type StencilShape, ImageEditor } from '@docyrus/ui/components/image-editor';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { type PropControl, PropControls } from '@/components/prop-controls';

const GALLERY_IMAGES = [
  'https://images.unsplash.com/photo-1535930749574-1399327ce78f?w=800&h=600&fit=crop',
  'https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=800&h=600&fit=crop',
  'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=800&h=600&fit=crop',
  'https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=800&h=600&fit=crop'
];

export function ImageEditorDemo() {
  const [selectedIndex, setSelectedIndex] = useState(0);
  const [savedImage, setSavedImage] = useState<string | null>(null);
  const [open, setOpen] = useState(false);

  const [stencilShape, setStencilShape] = useState<StencilShape>('rectangle');
  const [variant, setVariant] = useState<'default' | 'compact'>('default');
  const [size, setSize] = useState<'sm' | 'default' | 'lg'>('default');
  const [aspectRatio, setAspectRatio] = useState(0);
  const [disabled, setDisabled] = useState(false);

  const handleSave = useCallback((dataUrl: string) => {
    setSavedImage(dataUrl);
  }, []);

  const controls: PropControl[] = [
    {
      type: 'select',
      name: 'stencilShape',
      label: 'Stencil Shape',
      value: stencilShape,
      onChange: v => setStencilShape(v as StencilShape),
      options: [{ value: 'rectangle', label: 'Rectangle' }, { value: 'circle', label: 'Circle' }]
    },
    {
      type: 'select',
      name: 'variant',
      label: 'Variant',
      value: variant,
      onChange: v => setVariant(v as 'default' | 'compact'),
      options: [{ value: 'default', label: 'Default' }, { value: 'compact', label: 'Compact' }]
    },
    {
      type: 'select',
      name: 'size',
      label: 'Size',
      value: size,
      onChange: v => setSize(v as 'sm' | 'default' | 'lg'),
      options: [{ value: 'sm', label: 'Small' }, { value: 'default', label: 'Default' }, { value: 'lg', label: 'Large' }]
    },
    {
      type: 'number',
      name: 'aspectRatio',
      label: 'Aspect Ratio',
      value: aspectRatio,
      onChange: setAspectRatio,
      min: 0,
      max: 10,
      placeholder: '0 = free'
    },
    {
      type: 'boolean',
      name: 'disabled',
      label: 'Disabled',
      value: disabled,
      onChange: setDisabled
    }
  ];

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>

      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            
          </div>
        </div>
      </div>

      <div className="space-y-4">
        <ImageEditor
          src={GALLERY_IMAGES[selectedIndex]}
          stencilShape={stencilShape}
          variant={variant}
          size={size}
          aspectRatio={aspectRatio > 0 ? aspectRatio : undefined}
          disabled={disabled}
          onSave={handleSave} />

        <div className="flex gap-2 overflow-x-auto pb-1">
          {GALLERY_IMAGES.map((src, i) => (
            <button
              key={src}
              type="button"
              className={cn(
                'relative shrink-0 overflow-hidden rounded-md border-2 transition-all',
                i === selectedIndex ? 'border-primary ring-2 ring-primary/20' : 'border-transparent opacity-60 hover:opacity-100'
              )}
              onClick={() => {
                setSelectedIndex(i);
                setSavedImage(null);
              }}>
              <img
                src={src}
                alt={`Gallery image ${i + 1}`}
                width={80}
                height={60}
                className="h-14 w-20 object-cover" />
            </button>
          ))}
        </div>

        {savedImage ? (
          <div className="space-y-2">
            <p className="text-xs font-medium text-muted-foreground">Saved result:</p>

            <img
              src={savedImage}
              alt="Edited"
              width={256}
              height={256}
              className="max-h-48 rounded-md border object-contain" />
          </div>
        ) : null}
      </div>
    </div>
  );
}
```

## Installation

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

**Dependencies:**
- [react-advanced-cropper](https://www.npmjs.com/package/react-advanced-cropper)
- [advanced-cropper](https://www.npmjs.com/package/advanced-cropper)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
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

```tsx

```

### Compact Variant

```tsx

```

## 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. |