or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

component.mdindex.mdtypes.mdutils.md
tile.json

tessl/npm-react-image-crop

A responsive image cropping tool for React with no dependencies.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-image-crop@11.0.x

To install, run

npx @tessl/cli install tessl/npm-react-image-crop@11.0.0

index.mddocs/

React Image Crop

React Image Crop is a responsive image cropping tool for React with zero dependencies. It provides a complete cropping interface with support for pixel and percentage coordinates, touch interactions, keyboard accessibility, and various cropping modes including fixed aspect ratios and circular crops.

Package Information

  • Package Name: react-image-crop
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install react-image-crop

Core Imports

// Default import (recommended)
import ReactCrop, { Crop, PixelCrop, PercentCrop, AriaLabels } from "react-image-crop";
import "react-image-crop/dist/ReactCrop.css";

// Named import (alternative)
import { ReactCrop, Crop, PixelCrop, PercentCrop, AriaLabels } from "react-image-crop";

// For legacy compatibility
import { Component } from "react-image-crop"; // Same as ReactCrop

CSS Import Options:

// Compiled CSS (recommended for most projects)
import "react-image-crop/dist/ReactCrop.css";

// SCSS source (for projects with SCSS build setup)
import "react-image-crop/src/ReactCrop.scss";

For CommonJS:

const ReactCrop = require("react-image-crop").default;
// or
const { ReactCrop, Component } = require("react-image-crop");

You can also import individual utilities:

import { 
  makeAspectCrop, 
  centerCrop, 
  convertToPixelCrop, 
  convertToPercentCrop 
} from "react-image-crop";

Basic Usage

import React, { useState } from "react";
import ReactCrop, { Crop, PixelCrop, PercentCrop } from "react-image-crop";
import "react-image-crop/dist/ReactCrop.css";

function CropDemo({ src }: { src: string }) {
  const [crop, setCrop] = useState<Crop>();

  return (
    <ReactCrop 
      crop={crop} 
      onChange={(pixelCrop: PixelCrop, percentCrop: PercentCrop) => setCrop(pixelCrop)}
    >
      <img src={src} alt="Crop me" />
    </ReactCrop>
  );
}

Architecture

React Image Crop is built around several key components:

  • ReactCrop Component: Main React component that handles all cropping interactions
  • Crop Types: TypeScript interfaces defining crop coordinates in pixels or percentages
  • Utility Functions: Helper functions for crop manipulation, aspect ratio enforcement, and coordinate conversion
  • Event System: Comprehensive callback system for drag events and crop changes
  • Accessibility: Full keyboard navigation and screen reader support

The library uses a controlled component pattern where the parent component manages crop state through the required onChange callback.

Capabilities

React Component

The main ReactCrop component providing the complete cropping interface with drag handles, keyboard navigation, and comprehensive customization options.

interface ReactCropProps {
  crop?: Crop;
  onChange: (crop: PixelCrop, percentageCrop: PercentCrop) => void;
  children?: React.ReactNode;
  aspect?: number;
  circularCrop?: boolean;
  disabled?: boolean;
  locked?: boolean;
  minWidth?: number;
  minHeight?: number;
  maxWidth?: number;
  maxHeight?: number;
  onComplete?: (crop: PixelCrop, percentageCrop: PercentCrop) => void;
  onDragStart?: (e: PointerEvent) => void;
  onDragEnd?: (e: PointerEvent) => void;
  renderSelectionAddon?: (state: ReactCropState) => React.ReactNode;
  ruleOfThirds?: boolean;
  keepSelection?: boolean;
  ariaLabels?: AriaLabels;
  className?: string;
  style?: React.CSSProperties;
}

class ReactCrop extends PureComponent<ReactCropProps, ReactCropState> {}

React Component

Crop Types

TypeScript interfaces and types for defining crop coordinates and dimensions in both pixel and percentage units.

interface Crop {
  x: number;
  y: number;
  width: number;
  height: number;
  unit: 'px' | '%';
}

interface PixelCrop extends Crop {
  unit: 'px';
}

interface PercentCrop extends Crop {
  unit: '%';
}

type Ords = 'n' | 's' | 'e' | 'w' | 'nw' | 'ne' | 'se' | 'sw';

Crop Types

Utility Functions

Helper functions for crop manipulation including aspect ratio enforcement, coordinate conversion, and crop positioning utilities.

function makeAspectCrop(
  crop: Partial<Crop>, 
  aspect: number, 
  containerWidth: number, 
  containerHeight: number
): Crop;

function centerCrop(
  crop: Partial<Crop>, 
  containerWidth: number, 
  containerHeight: number
): Crop;

function convertToPixelCrop(
  crop: Partial<Crop>, 
  containerWidth: number, 
  containerHeight: number
): PixelCrop;

function convertToPercentCrop(
  crop: Partial<Crop>, 
  containerWidth: number, 
  containerHeight: number
): PercentCrop;

Utility Functions