ImageCrop

A powerful component for cropping images with customizable aspect ratios, drag-and-drop functionality, and real-time preview.

Import

import { ImageCrop } from '@akitectio/aki-ui'

Modal/Popup Pattern

ImageCrop works perfectly in modal patterns using Aki UI's Modal component. This provides a focused editing experience without leaving the current page.

This will open the crop modal using Aki UI Modal component

Implementation Code

import { Modal, ModalHeader, ModalBody, ModalFooter, ImageCrop } from '@akitectio/aki-ui'

function ImageCropModal() {
  const [showModal, setShowModal] = useState(false)
  const [selectedFile, setSelectedFile] = useState<File | null>(null)
  const [croppedImage, setCroppedImage] = useState('')
  const [borderRadiusPercent, setBorderRadiusPercent] = useState(25)

  const handleFileSelect = (file: File) => {
    setSelectedFile(file)
    setShowModal(true)
  }

  const handleCropComplete = (crop: any, croppedImageUrl: string) => {
    setCroppedImage(croppedImageUrl)
    setShowModal(false)
  }

  return (
    <>
      {/* File Picker Button */}
      <button onClick={triggerFilePicker}>
        Select Image to Crop
      </button>

      {/* Aki UI Modal */}
      <Modal isOpen={showModal} onClose={() => setShowModal(false)} size="xl">
        <ModalHeader onClose={() => setShowModal(false)}>
          Crop Your Image
        </ModalHeader>
        
        <ModalBody>
          <ImageCrop
            file={selectedFile}
            enableFilePicker={false}
            defaultAspectRatio={1}
            size="lg"
            enableZoom={true}
            minZoom={0.5}
            maxZoom={3}
            showBorderRadiusControl={true}
            cropBorderRadiusPercent={borderRadiusPercent}
            onBorderRadiusPercentChange={setBorderRadiusPercent}
            onCropComplete={handleCropComplete}
          />
        </ModalBody>
        
        <ModalFooter>
          <button onClick={() => setShowModal(false)}>Cancel</button>
        </ModalFooter>
      </Modal>

      {/* Display Result */}
      {croppedImage && (
        <img 
          src={croppedImage} 
          alt="Cropped" 
          style={{ borderRadius: borderRadiusPercent + '%' }}
        />
      )}
    </>
  )
}

Key Features

🎯 Interactive Cropping

  • • Drag to move crop area
  • • 8 resize handles for precise control
  • • Visual grid lines (rule of thirds)
  • • Real-time crop preview

📐 Aspect Ratio Control

  • • Predefined ratios (1:1, 4:3, 16:9, etc.)
  • • Custom aspect ratio support
  • • Free-form cropping mode
  • • Automatic ratio enforcement

📁 File Handling

  • • File object upload support
  • • URL-based image loading
  • • Canvas-based processing
  • • PNG/JPEG output formats

🔍 Zoom & Navigation

  • • Mouse wheel zoom support
  • • Zoom in/out/reset buttons
  • • Configurable zoom range (0.5x-3x)
  • • Real-time zoom level display

🎨 Border Radius Control

  • • Interactive slider control (0-50%)
  • • Perfect circles for avatars
  • • Real-time preview
  • • Percentage-based radius

API Reference

PropTypeDefaultDescription
fileFile-File object for upload
defaultAspectRationumber | null1Initial aspect ratio
size'sm' | 'md' | 'lg''md'Component size variant
enableZoombooleantrueEnable zoom functionality
minZoomnumber0.5Minimum zoom level
maxZoomnumber3.0Maximum zoom level
onCropCompletefunction-Callback when crop is finalized
showBorderRadiusControlbooleanfalseShow border radius control slider
cropBorderRadiusPercentnumber-Custom border radius percentage (0-50)
onBorderRadiusPercentChangefunction-Border radius percent change callback