docs/components/cropper

Cropperpreview

An image cropper with handles, a fixed or free aspect ratio, zoom, rotation and touch gestures.

import { Cropper } from "@logic-ui/react/cropper"

source markdown edit

Crop

Usage guidelines#

Everything is headless: the parts place the image and the crop, and handle the gestures, the keyboard and the math. How the crop, the handles, the grid and the darkened area look is yours, through data attributes.
One gesture engine: dragging a handle, the crop or the image, pinching and the wheel are handled together in Cropper.Viewport, with pointer events, so mouse, pen and touch work the same and never fight over a press.
Image pixels in, image pixels out: defaultCoordinates, minWidth, onCoordinatesChange and getCanvas() all speak in pixels of the image, whatever its size on screen.
Ported from Advanced Cropper: the algorithms come from advanced-cropper and react-advanced-cropper by Norserium, merged into one entry point. The rectangle and circle stencils are one Cropper.Stencil, lines and handles one Cropper.Handle, and FixedCropper is the stencilSize prop.

Anatomy#

Import the component and assemble its parts:

Anatomy

import { Cropper } from "@logic-ui/react/cropper";

<Cropper.Root>
  <Cropper.Viewport>
    <Cropper.Image />
    <Cropper.Stencil>
      <Cropper.Grid />
      <Cropper.Handle position="top-left" />
    </Cropper.Stencil>
  </Cropper.Viewport>
  <Cropper.Preview />
  <Cropper.ZoomIn />
  <Cropper.ZoomOut />
  <Cropper.Rotate />
  <Cropper.Flip />
  <Cropper.Reset />
</Cropper.Root>;

Examples#

Getting started#

Cropper.Root loads src and holds the crop. Give Cropper.Viewport a size: the image fits in it and the crop starts at 80% of the image. Without handles, the crop keeps its size and moves.

A square crop

<Cropper.Root src={url} aspectRatio={1}>
  <Cropper.Viewport className="h-96 w-full">
    <Cropper.Image />
    <Cropper.Stencil className="shadow-[0_0_0_9999px_rgb(0_0_0/0.6)] outline outline-white" />
  </Cropper.Viewport>
</Cropper.Root>

Handles#

Cropper.Handle resizes the crop from a corner (top-left, top-right, bottom-right, bottom-left) or an edge (top, right, bottom, left). It has data-position: place it with that. An edge handle can be a strip along the edge, as in the demo above, or a small bar in its middle. Hold Shift while dragging to keep the aspect ratio.

A corner bracket, like a phone's editor

<Cropper.Handle
  position="top-left"
  className="absolute top-0 left-0 size-8 border-t-[3px] border-l-[3px] border-white"
/>

Aspect ratio and size#

aspectRatio takes a number or a range, { minimum: 1, maximum: 2 }. minWidth, minHeight, maxWidth and maxHeight are in image pixels. When they change, the crop is fitted to them around its center.

Between square and 2:1, at least 200 px wide

<Cropper.Root src={url} aspectRatio={{ minimum: 1, maximum: 2 }} minWidth={200}>

Fixed stencil#

stencilSize keeps the crop's size on screen: the image moves and zooms behind it, and the crop can't be moved or resized. Round it with rounded-full for a profile picture, and drive the zoom from a Base UI slider with useCropperRootContext() and useCropperRootStateContext().

Move and scale

A zoom slider

const { actions } = useCropperRootContext();
const { zoom } = useCropperRootStateContext();

<Slider.Root
  min={0}
  max={1}
  step={0.01}
  value={zoom}
  onValueChange={(value) => actions.setZoom(value as number)}
>

Where the image may go#

imageRestriction sets how far the image can move and zoom out:

"fit-area" (default): the image can't be zoomed out past the viewport, and the crop stays on the image.
"fill-area": the image always fills the viewport.
"stencil": only the crop stays on the image, the view is free. Best with stencilSize.
"none": no limit; the crop can leave the image, and getCanvas() fills the rest with fillColor.

Getting the result#

actionsRef receives the actions. getCanvas() draws the crop on a canvas, rotated and flipped, at its size in image pixels or at the size you ask: width, height, maxWidth, maxHeight or maxArea. For an image from another origin, the server must send CORS headers: crossOrigin is "anonymous" by default.

Upload the crop

const actionsRef = React.useRef<CropperRootActions>(null);

async function upload() {
  const canvas = actionsRef.current?.getCanvas({ maxWidth: 1600 });
  canvas?.toBlob((blob) => blob && send(blob), "image/webp");
}

<Cropper.Root src={url} actionsRef={actionsRef}>

onCoordinatesChange reports the crop in whole image pixels as it changes; onCoordinatesCommitted once a gesture ends or after a button or key press, like a slider's onValueCommitted. Both receive eventDetails.reason: "handle-drag", "wheel", "keyboard", "zoom-in-press" …

To send the crop to a server that crops, use getCoordinates() with getState().transforms for the rotation and flip.

In a dialog#

Put the cropper in a Base UI Dialog.Popup to crop a photo the user picks: give the file an object URL as src, open the dialog, and read getCanvas() when they save. Cropper.Viewport measures itself when the popup opens, and again if its size changes, so nothing has to wait for the dialog.

The profile card below takes a click or a dropped image on its cover or its photo, and opens an editor shaped for each: a fixed circle for the photo (stencilSize from the viewport's size), a 3:1 frame for the cover. The editor is a sheet on phones and a card on larger screens, with frosted bars over the photo, a zoom dial, rotate, flip and reset, and a live Cropper.Preview at the result's shape. It shows a spinner while the image loads and a message when it can't be opened (data-loading, data-error), and Save waits for the image.

Add a coverAM

Ava Martin

@ava · Photographer

Click the cover or the photo, or drop an image on it.

Crop a chosen file

function choose(event: React.ChangeEvent<HTMLInputElement>) {
  const file = event.target.files?.[0];
  if (file) {
    setSrc(URL.createObjectURL(file));
    setOpen(true);
  }
}

<Dialog.Root open={open} onOpenChange={setOpen}>
  <Dialog.Portal>
    <Dialog.Backdrop />
    <Dialog.Popup>
      <Dialog.Title>Crop your photo</Dialog.Title>
      <Cropper.Root src={src} aspectRatio={1} actionsRef={actionsRef}>
        <Cropper.Viewport className="h-80">…</Cropper.Viewport>
        <Dialog.Close>Cancel</Dialog.Close>
        <button onClick={save}>Save</button>
      </Cropper.Root>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>;

Revoke the object URL (URL.revokeObjectURL) once it is no longer shown.

Account picture, step by step#

A profile picture flow in the style of Google's account settings, in Material 3's dark colours: one dialog walks through the steps, each sliding in from the side it comes from.

Profile picture shows the current picture, with Change and Remove; removing asks first and shows what replaces it.
Change profile picture offers your photos in a grid, or an upload: drag a photo onto the drop zone or pick one, in Base UI Tabs with a sliding indicator.
Crop & rotate shows a square crop with the circle people will see, round handles on its corners, and Rotate and Reset. Save as profile picture draws 512 × 512 px with getCanvas(), shows its progress, and returns to the first step with the new picture.

Ava Martin

ava.martin@example.com

Open a photo and press Edit to crop it full screen without leaving the viewer, like a phone's gallery: frosted bars over the photo, aspect presets, a zoom dial, rotate, flip and reset, with the crop's size in pixels as you drag. Done puts the cropped photo in the gallery, and it flies back to its tile; editing it again starts from the same crop, Revert brings the original back, and the cropped photo can be downloaded.

The editor is a Cropper laid over a Lightbox viewer inside Lightbox.Popup, so the dialog keeps focus in it. It keeps its keys to itself: the arrows move the crop instead of the photo, and Esc cancels the edit instead of closing the viewer.

Recents

Open a photo, then Edit

Edit the photo shown, inside the popup

<Lightbox.Popup>
  <Lightbox.Viewport>…</Lightbox.Viewport>
  <button onClick={() => setEditing(true)}>Edit</button>
  {editing && (
    // Keys pressed in the editor stay there: Esc cancels the edit.
    <div
      className="absolute inset-0 bg-black"
      onKeyDown={(event) => {
        if (event.key === "Escape") setEditing(false);
        event.stopPropagation();
      }}
    >
      <Cropper.Root src={original.src} actionsRef={actionsRef}>
        …
      </Cropper.Root>
    </div>
  )}
</Lightbox.Popup>

Saving replaces the item in items with the cropped image (getCanvas().toDataURL()) and its new width and height; the item keeps its value, so the viewer stays on it.

Restoring a crop#

defaultCoordinates sets the first crop in image pixels; a size without left and top is centered. defaultVisibleArea sets the first view, and defaultTransforms the rotation and flip. To restore a crop, save getState() and pass its coordinates, visibleArea and transforms back as these defaults: they fit the viewport whatever its size.

Preview#

Cropper.Preview shows the crop live, scaled to fit it. Give it the crop's shape with aspect-(--cropper-aspect-ratio), set on Cropper.Root.

A live preview

<Cropper.Preview className="aspect-(--cropper-aspect-ratio) w-40 rounded" />

Animations#

Buttons, keys and the end of a gesture move the crop and the image to their new place at once, and set data-transitioning on the parts for transitionDuration (350 ms). Animate them with it and --cropper-transition-duration; drags wait for the animation to end. Set transitionDuration={0} to turn it off.

Slide to the new place

<Cropper.Image className="data-transitioning:transition-transform data-transitioning:duration-(--cropper-transition-duration)" />
<Cropper.Stencil className="data-transitioning:transition-[width,height,transform] data-transitioning:duration-(--cropper-transition-duration)" />

Styling#

Every part is unstyled. Style the cropper with Tailwind (or any CSS), using the parts' data attributes and CSS variables:

Cropper.Root, Cropper.Viewport and Cropper.Preview have data-loading, data-loaded and data-error. Fade the viewport in with data-loaded, and show a message with data-error.
Cropper.Root has --cropper-image-aspect-ratio, to give Cropper.Viewport the image's shape (aspect-(--cropper-image-aspect-ratio) max-h-96), and --cropper-aspect-ratio, the crop's.
Cropper.Viewport clips its content and handles touch itself (overflow: hidden, touch-action: none). It has data-interacting during a drag, a pinch or a wheel zoom: data-interacting:cursor-grabbing.
Cropper.Viewport's padding is room the crop and the fitted image stay out of, while a zoomed or moved image still shows there. Make it full screen and pad it by the height of bars laid over it: the photo runs under them, as in the lightbox example, where the bars are frosted with bg-neutral-950/50 backdrop-blur-xl.
Cropper.Stencil is placed with transform, width and height. Darken the image around it with a large shadow, shadow-[0_0_0_9999px_rgb(0_0_0/0.6)], and shape it with rounded-full. It has data-movable, data-moving and data-resizing.
Cropper.Grid renders rows × columns cells with data-row and data-column; lay them out with grid-cols-[repeat(var(--cropper-grid-columns),minmax(0,1fr))] and the same for rows (the variables hold counts, so they need repeat()) and show them with data-interacting.
Cropper.Handle has data-position and data-resizing while dragged.

Keyboard#

Cropper.Stencil and every Cropper.Handle are focusable:

On the crop, the arrow keys move it by 10 px on screen, 50 with Shift, and + and − zoom.
On a handle, the arrow keys move its corner or edge, 50 px with Shift.

API reference#

Cropper.Root#

Holds the image, the crop and the view, and provides them to the parts. Renders a <div> element.

Props

src: string | null
URL of the image to crop.
crossOrigin: "anonymous" | "use-credentials"default "anonymous"
CORS mode of the image. getCanvas() needs it for an image from another origin, and the server must allow it; null loads the image without CORS.
aspectRatio: CropperAspectRatio
Aspect ratio (width / height) of the crop: a number, or a range.
minWidth: number
Smallest width of the crop, in image pixels.
minHeight: number
Smallest height of the crop, in image pixels.
maxWidth: number
Largest width of the crop, in image pixels.
maxHeight: number
Largest height of the crop, in image pixels.
stencilSize: CropperSize | ((state: CropperState) => CropperSize)
Fixes the crop's size on screen (pixels): the image moves and zooms behind it, and the crop can't be moved or resized. It keeps within aspectRatio.
imageRestriction: "fill-area" | "fit-area" | "stencil" | "none"default "fit-area"
Where the image may go relative to the crop and the viewport.
"fill-area" the image always fills the viewport, and the crop stays on the image.
"fit-area"default the image can't be zoomed out past the viewport on both axes, and the crop stays on the image.
"stencil" only the crop stays on the image; the view is free.
"none" no limit; the crop can leave the image.
adjustStencil: booleandefault true
Whether zooming resizes the crop with the image, rather than keeping its size on screen. Ignored with stencilSize.
defaultCoordinates: Partial<CropperCoordinates> | ((state: CropperState) => Partial<CropperCoordinates>)
The crop to start from, in image pixels. A size without left and top is centered. 80% of the image by default.
defaultVisibleArea: CropperCoordinates | ((state: CropperState) => CropperCoordinates)
The part of the image to show first, in image pixels. Wins over defaultCoordinates.
defaultTransforms: CropperDefaultTransforms
The rotation and flip to start from.
transitionDuration: numberdefault 350
How long a change from a button, a key or the end of a gesture animates (ms); drags wait for it. Animate with data-transitioning and --cropper-transition-duration. 0 turns it off.
disabled: booleandefault false
Whether the cropper ignores the user.
onCoordinatesChange: ( coordinates: CropperCoordinates | null, eventDetails: CropperRootChangeEventDetails, ) => void
Called when the crop, in whole image pixels, changes.
onCoordinatesCommitted: ( coordinates: CropperCoordinates | null, eventDetails: CropperRootChangeEventDetails, ) => void
Called with the crop when a change is complete: at the end of a gesture, or after a button or key press.
onStatusChange: (status: CropperRootStatus) => void
Called when status changes: the image loads, shows or fails.
actionsRef: React.RefObject<CropperRootActions | null>
Receives the actions: getCanvas(), getCoordinates(), rotate() …
className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-loading: Present while the image loads, or waits for Cropper.Viewport to have a size.
data-loaded: Present once the image is on screen with its crop.
data-error: Present when the image failed to load.
data-disabled: Present when the cropper ignores the user.
data-interacting: Present while a drag, pinch or wheel zoom is in progress.
data-transitioning: Present while a change animates, for --cropper-transition-duration.

CSS variables

--cropper-image-aspect-ratio: Natural aspect ratio of the image, to size Cropper.Viewport to it.
--cropper-aspect-ratio: Aspect ratio of the crop, to size Cropper.Preview to it.
--cropper-transition-duration: The transitionDuration prop, for the transitions of data-transitioning.

Cropper.Viewport#

The area that shows the image and the crop. Its size on screen is the cropper's: give it one, such as aspect-(--cropper-image-aspect-ratio). Its padding is room the crop and the fitted image stay out of, where a zoomed or moved image still shows: under bars laid over it, for example. Drags, pinches and the wheel on it move and zoom the image. Renders a <div> element.

Props

zoomOnWheel: booleandefault true
Whether the wheel and a trackpad pinch zoom the image.
zoomOnPinch: booleandefault true
Whether two fingers pinch to zoom the image.
rotateOnPinch: booleandefault false
Whether two fingers turn the image.
panOnDrag: booleandefault true
Whether dragging the image moves it.
className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-loading: Present while the image loads, or waits for Cropper.Viewport to have a size.
data-loaded: Present once the image is on screen with its crop.
data-error: Present when the image failed to load.
data-disabled: Present when the cropper ignores the user.
data-interacting: Present while a drag, pinch or wheel zoom is in progress.
data-transitioning: Present while a change animates, for --cropper-transition-duration.

Cropper.Image#

The image, placed under the crop as the view moves and zooms. Renders nothing until the image is on screen. Its alt is empty unless you set one. Renders an <img> element.

Props

className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-transitioning: Present while a change animates, for --cropper-transition-duration.

Cropper.Stencil#

The crop, placed over the image in Cropper.Viewport. Drag it or use the arrow keys to move it (Shift for larger steps), and + and − to zoom. Style the area outside it with a large shadow, and its shape with border-radius. Renders nothing until the image is on screen. Renders a <div> element.

Props

movable: booleandefault true
Whether the crop can be dragged. A drag on a fixed crop moves the image.
className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-movable: Present when the crop can be dragged and moved with the arrow keys.
data-moving: Present while the crop is dragged.
data-resizing: Present while a handle is dragged.
data-interacting: Present while a drag, pinch or wheel zoom is in progress.
data-transitioning: Present while a change animates, for --cropper-transition-duration.
data-disabled: Present when the cropper ignores the user.

Cropper.Handle#

Resizes the crop from a corner or an edge: drag it, or use the arrow keys (Shift for larger steps). Hold Shift while dragging to keep the aspect ratio. Place it in Cropper.Stencil and position it with data-position; an edge handle can be styled as a line along the edge. Renders a <div> element.

Props

position*: "top-left" | "top" | "top-right" | "right" | "bottom-right" | "bottom" | "bottom-left" | "left"
The corner or edge of the crop it resizes.
disabled: booleandefault false
Whether it can't resize the crop. Handles are disabled with stencilSize too.
className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-position: The corner or edge the handle resizes: top-left, top, top-right, right, bottom-right, bottom, bottom-left or left.
data-resizing: Present while the handle is dragged.
data-disabled: Present when the handle can't resize the crop.

Cropper.Grid#

Guides over the crop, such as the rule of thirds: renders rows × columns cells, each a <div> with data-row and data-column. Lay them out with repeat(var(--cropper-grid-columns), 1fr) and the same for rows, and show them with data-interacting. Hidden from assistive technology. Renders a <div> element.

Props

rows: numberdefault 3
Number of rows.
columns: numberdefault 3
Number of columns.
className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-interacting: Present while a drag, pinch or wheel zoom is in progress: show the grid then.
data-row: On each cell: its row, from 0.
data-column: On each cell: its column, from 0.

CSS variables

--cropper-grid-rows: The rows prop, a count: grid-template-rows: repeat(var(--cropper-grid-rows), 1fr).
--cropper-grid-columns: The columns prop, a count: grid-template-columns: repeat(var(--cropper-grid-columns), 1fr).

Cropper.Preview#

Shows the cropped part of the image, live, scaled to fit the element. Give it the crop's ratio with aspect-(--cropper-aspect-ratio); with another ratio, the crop is centered and the image shows around it. Renders a <div> element with an <img> inside.

Props

className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-loading: Present while the image loads, or waits for Cropper.Viewport to have a size.
data-loaded: Present once the image is on screen with its crop.
data-error: Present when the image failed to load.
data-transitioning: Present while a change animates, for --cropper-transition-duration.

Cropper.ZoomIn#

Zooms the image in by one step. Disabled at the closest view. Renders a <button> element.

Props

className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-disabled: Present when the action can't run now.

Cropper.ZoomOut#

Zooms the image out by one step. Disabled at the widest view. Renders a <button> element.

Props

className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-disabled: Present when the action can't run now.

Cropper.Rotate#

Turns the image by angle degrees. Renders a <button> element.

Props

angle: numberdefault 90
Degrees to turn the image by, clockwise; negative turns it counterclockwise.
className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-disabled: Present when the action can't run now.

Cropper.Flip#

Mirrors the image. Renders a <button> element.

Props

orientation: "horizontal" | "vertical"default "horizontal"
The axis the image is mirrored across.
"horizontal"default left and right swap.
"vertical" top and bottom swap.
className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-disabled: Present when the action can't run now.

Cropper.Reset#

Starts over with the default crop, rotation and view. Renders a <button> element.

Props

className: string
CSS class applied to the element.
style: React.CSSProperties
Style applied to the element.
render: React.ReactElement | ((props, state) => React.ReactElement)
Replaces the element with another tag or component, or composes it with one. Takes an element, or a function that receives the props and the state.

Data attributes

data-disabled: Present when the action can't run now.

CropperFlipOrientationunion#

The axis the image is mirrored across, as seen on screen:

Values

"horizontal": left and right swap.
"vertical": top and bottom swap.

CropperHandlePositionunion#

The corner or edge of the crop a handle resizes: - "top-left", "top-right", "bottom-right", "bottom-left": a corner, both axes. - "top", "right", "bottom", "left": an edge, one axis.

Values

"top-left"
"top"
"top-right"
"right"
"bottom-right"
"bottom"
"bottom-left"
"left"

CropperRootChangeEventDetailstype#

Details of a change: its reason and the native event.

Properties

reason*: "none" | "image-load" | "viewport-resize" | "settings-change" | "stencil-drag" | "handle-drag" | "image-drag" | "pinch" | "wheel" | "keyboard" | "zoom-in-press" | "zoom-out-press" | "rotate-press" | "flip-press" | "reset-press" | "imperative-action"
The reason for the event.
event*: ReasonToEvent<Reason>
The native event associated with the custom event.

CropperRootChangeEventReasonunion#

Why the crop changed, as passed in eventDetails.reason:

Values

"none": Another cause.
"image-load": A new image was shown, or the cropper started over on it.
"viewport-resize": Cropper.Viewport changed size.
"settings-change": A prop such as aspectRatio changed and the crop was fitted to it.
"stencil-drag": Cropper.Stencil was dragged.
"handle-drag": A Cropper.Handle was dragged.
"image-drag": The image was dragged.
"pinch": Two fingers pinched or turned the image.
"wheel": The wheel or a trackpad pinch zoomed the image.
"keyboard": A key moved, resized or zoomed the crop.
"zoom-in-press": Cropper.ZoomIn was pressed.
"zoom-out-press": Cropper.ZoomOut was pressed.
"rotate-press": Cropper.Rotate was pressed.
"flip-press": Cropper.Flip was pressed.
"reset-press": Cropper.Reset was pressed.
"imperative-action": A call on actionsRef or on the context's actions.

CropperRootImageRestrictionunion#

Where the image may go relative to the crop and the viewport:

Values

"fill-area": the image always fills the viewport, and the crop stays on the image.
"fit-area": the image can't be zoomed out past the viewport on both axes, and the crop stays on the image.
"stencil": only the crop stays on the image; the view is free.
"none": no limit; the crop can leave the image.

CropperRootStatusunion#

Where the image is:

Values

"idle": there is no src.
"loading": the image loads, or waits for Cropper.Viewport to have a size.
"loaded": the image is on screen with its crop.
"error": the image failed to load.

CropperLoadedImagetype#

The image the cropper shows, once loaded.

Properties

src*: string
width*: number
Natural size.
height*: number
element*: HTMLImageElement

CropperRootActionstype#

What the cropper can do from code: through actionsRef, or through useCropperRootContext() in a part of your own.

Properties

getState*: () => CropperState | null
The full state, or null before the image is on screen.
getCoordinates*: () => CropperCoordinates | null
The crop in whole pixels of the (rotated) image.
getCanvas*: (options?: CropperCanvasOptions) => HTMLCanvasElement | null
Draws the crop on a new canvas. The image must allow it (crossOrigin).
setCoordinates*: ( coordinates: Exclude<CropperCoordinatesTransform, null>, ) => void
Moves or resizes the crop, in image pixels; a size without position is kept centered.
setState*: (state: CropperState) => void
Replaces the state, such as one saved from getState().
zoom*: (factor: number, center?: CropperPoint) => void
Zooms by factor (above 1 zooms in), around a point of the image or the center.
setZoom*: (zoom: number) => void
Zooms to zoom, from 0 (widest view) to 1 (closest view).
move*: (left: number, top: number) => void
Moves the view by image pixels.
rotate*: (angle: number) => void
Rotates the image by angle degrees, clockwise.
flip*: (horizontal: boolean, vertical?: boolean) => void
Mirrors the image as seen on screen.
reset*: () => void
Starts over with the default crop.

CropperAspectRatiotype#

The aspect ratio (width / height) the crop must keep: one number, or a range. Leave out a bound to leave that side free.

Properties

toString*
valueOf*
toLocaleString*

CropperCanvasOptionstype#

Options of the canvas getCanvas() draws the crop on.

Properties

width: number
Width of the result; the height follows the crop's aspect ratio.
height: number
Height of the result; the width follows the crop's aspect ratio.
minWidth: number
minHeight: number
maxWidth: number
maxHeight: number
maxArea: number
Largest number of pixels (width × height) of the result.
fillColor: stringdefault "transparent"
Colour drawn behind the image, seen where the crop leaves it.
imageSmoothingEnabled: booleandefault true
imageSmoothingQuality: "high" | "low" | "medium"default "high"

CropperCoordinatestype#

A rectangle: its top left corner and its size.

Properties

left*: number
top*: number
width*: number
height*: number

CropperDefaultTransformstype#

Transforms to start from; a missing field keeps the image as it is.

Properties

rotate: number
flip: { horizontal?: boolean | undefined; vertical?: boolean | undefined; }

CropperPointtype#

A point, in image pixels unless stated otherwise.

Properties

left*: number
top*: number

CropperPositionRestrictionstype#

Edges a rectangle must stay within, in image pixels. A missing edge is free.

Properties

left: number
top: number
right: number
bottom: number

CropperSizetype#

A size, in image pixels unless stated otherwise.

Properties

width*: number
height*: number

CropperSizeRestrictionstype#

Smallest and largest size, in image pixels.

Properties

minWidth*: number
minHeight*: number
maxWidth*: number
maxHeight*: number

CropperTransformstype#

Rotation in degrees and mirroring applied to the image.

Properties

rotate*: number
flip*: { horizontal: boolean; vertical: boolean; }

Cropperpreview

Usage guidelines#

Anatomy#

Examples#

Getting started#

Handles#

Aspect ratio and size#

Fixed stencil#

Where the image may go#

Getting the result#

In a dialog#

Account picture, step by step#

In a lightbox#

Recents

Restoring a crop#

Preview#

Animations#

Styling#

Keyboard#

API reference#

Cropper.Root#

Cropper.Viewport#

Cropper.Image#

Cropper.Stencil#

Cropper.Handle#

Cropper.Grid#

Cropper.Preview#

Cropper.ZoomIn#

Cropper.ZoomOut#

Cropper.Rotate#

Cropper.Flip#

Cropper.Reset#

CropperFlipOrientationunion#

CropperHandlePositionunion#

CropperRootChangeEventDetailstype#

CropperRootChangeEventReasonunion#

CropperRootImageRestrictionunion#

CropperRootStatusunion#

CropperLoadedImagetype#

CropperRootActionstype#

CropperAspectRatiotype#

CropperCanvasOptionstype#

CropperCoordinatestype#

CropperDefaultTransformstype#

CropperPointtype#

CropperPositionRestrictionstype#

CropperSizetype#

CropperSizeRestrictionstype#

CropperTransformstype#