Skip to content
THE COMPONENT LIBRARY
Skip to content

Component reference

ImageCropper

Crop a profile image and inspect the exported result.

Preview

Live preview

Changes apply to this preview only.

AccountPNG · square · 512 px

Profile photo

Choose the part of the image shown next to your name.

Déplacez le cadre ou utilisez les flèches. Tirez une poignée pour redimensionner ; Maj accélère le déplacement.

Pimolu Studio product illustration

Crop position 12%, 12%, size 76% by 76%.

x 12%y 12%76% × 76%
{
  "x": 12,
  "y": 12,
  "width": 76,
  "height": 76
}

Width adapts to the available space

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Square avatar

Drag the crop area to move it, drag a handle to resize it, or use the arrow keys. Shift moves by five percent. The default zoom enlarges the image inside the stage without changing the crop rectangle.

Open preview

Cover crop

A 16 / 9 stage with a locked ratio is ready for a hero image. The stage crops the source with object-fit: cover and maps the visible rectangle back to the source pixels on export.

Open preview

Free crop and disabled state

Without aspectRatio, width and height resize independently. The same component can be disabled while an upload or a save is in flight.

Open preview

Usage

Canvas export requires a readable image source; cross-origin images need compatible CORS headers.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluCropArea

Type source
PimoluCropArea public API
NameTypeDefaultDescription
xRequirednumber—Public Pimolu prop; see the source declaration for details.
yRequirednumber—Public Pimolu prop; see the source declaration for details.
widthRequirednumber—Public Pimolu prop; see the source declaration for details.
heightRequirednumber—Public Pimolu prop; see the source declaration for details.
xRequired

number

No default extracted.

Public Pimolu prop; see the source declaration for details.

yRequired

number

No default extracted.

Public Pimolu prop; see the source declaration for details.

widthRequired

number

No default extracted.

Public Pimolu prop; see the source declaration for details.

heightRequired

number

No default extracted.

Public Pimolu prop; see the source declaration for details.

PimoluImageCropperLabels

Type source
PimoluImageCropperLabels public API
NameTypeDefaultDescription
cropperstring | undefined"Image cropper"Accessible name of the cropper region. Defaults to "Image cropper".
instructionsstring | undefined—Keyboard and pointer instructions.
cropAreastring | undefined"Crop area"Accessible name of the draggable crop area. Defaults to "Crop area".
zoomstring | undefined"Zoom"Zoom slider label. Defaults to "Zoom".
resetstring | undefined"Reset"Defaults to "Reset".
applystring | undefined"Crop image"Defaults to "Crop image".
status((crop: PimoluCropArea) => string) | undefinedan English position/size sentenceLive description announced after crop changes. Defaults to an English position/size sentence.
resizeTopLeftstring | undefined—Public Pimolu prop; see the source declaration for details.
resizeTopstring | undefined—Public Pimolu prop; see the source declaration for details.
resizeTopRightstring | undefined—Public Pimolu prop; see the source declaration for details.
resizeRightstring | undefined—Public Pimolu prop; see the source declaration for details.
resizeBottomRightstring | undefined—Public Pimolu prop; see the source declaration for details.
resizeBottomstring | undefined—Public Pimolu prop; see the source declaration for details.
resizeBottomLeftstring | undefined—Public Pimolu prop; see the source declaration for details.
resizeLeftstring | undefined—Public Pimolu prop; see the source declaration for details.
cropper

string | undefined

Default: "Image cropper"

Accessible name of the cropper region. Defaults to "Image cropper".

instructions

string | undefined

No default extracted.

Keyboard and pointer instructions.

cropArea

string | undefined

Default: "Crop area"

Accessible name of the draggable crop area. Defaults to "Crop area".

zoom

string | undefined

Default: "Zoom"

Zoom slider label. Defaults to "Zoom".

reset

string | undefined

Default: "Reset"

Defaults to "Reset".

apply

string | undefined

Default: "Crop image"

Defaults to "Crop image".

status

((crop: PimoluCropArea) => string) | undefined

Default: an English position/size sentence

Live description announced after crop changes. Defaults to an English position/size sentence.

resizeTopLeft

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

resizeTop

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

resizeTopRight

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

resizeRight

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

resizeBottomRight

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

resizeBottom

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

resizeBottomLeft

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

resizeLeft

string | undefined

No default extracted.

Public Pimolu prop; see the source declaration for details.

PimoluImageCropperProps

Type source
PimoluImageCropperProps public API
NameTypeDefaultDescription
srcRequiredPimoluImageCropperSource—Image URL, `File` or `Blob`. Object URLs are created and revoked.
altstring | undefinedan empty stringAlternative text of the preview image. Defaults to an empty string.
aspectRationumber | undefined—Locked crop ratio (width / height in pixels). Also fixes the stage ratio, so the default crop fills the stage exactly.
cropPimoluCropArea | undefined—Controlled crop area. Omit to let the cropper own it.
defaultCropPimoluCropArea | undefinedthe whole stageInitial crop when uncontrolled. Defaults to the whole stage.
onChange((crop: PimoluCropArea) => void) | undefined—Called on every move, resize, zoom-independent crop change and reset.
onComplete((blob: Blob | null, crop: PimoluCropArea) => void) | undefined—Called by the "Crop image" button. The blob is `null` when the browser cannot read the image size or a canvas context (for example in tests or a server-side render); the crop area is always provided.
outputTypestring | undefined"image/png"MIME type passed to `canvas.toBlob`. Defaults to "image/png".
outputQualitynumber | undefined—Quality (0–1) for lossy output types.
minZoomnumber | undefined1Smallest zoom. Values below 1 are raised to 1. Defaults to 1.
maxZoomnumber | undefined3Largest zoom. Defaults to 3.
defaultZoomnumber | undefined1Initial zoom. Defaults to 1.
disabledboolean | undefinedfalseDisable every interaction.
labelsPimoluImageCropperLabels | undefined—Localizable labels.
classNamestring | undefined—Class applied to the cropper wrapper.
srcRequired

PimoluImageCropperSource

No default extracted.

Image URL, `File` or `Blob`. Object URLs are created and revoked.

alt

string | undefined

Default: an empty string

Alternative text of the preview image. Defaults to an empty string.

aspectRatio

number | undefined

No default extracted.

Locked crop ratio (width / height in pixels). Also fixes the stage ratio, so the default crop fills the stage exactly.

crop

PimoluCropArea | undefined

No default extracted.

Controlled crop area. Omit to let the cropper own it.

defaultCrop

PimoluCropArea | undefined

Default: the whole stage

Initial crop when uncontrolled. Defaults to the whole stage.

onChange

((crop: PimoluCropArea) => void) | undefined

No default extracted.

Called on every move, resize, zoom-independent crop change and reset.

onComplete

((blob: Blob | null, crop: PimoluCropArea) => void) | undefined

No default extracted.

Called by the "Crop image" button. The blob is `null` when the browser cannot read the image size or a canvas context (for example in tests or a server-side render); the crop area is always provided.

outputType

string | undefined

Default: "image/png"

MIME type passed to `canvas.toBlob`. Defaults to "image/png".

outputQuality

number | undefined

No default extracted.

Quality (0–1) for lossy output types.

minZoom

number | undefined

Default: 1

Smallest zoom. Values below 1 are raised to 1. Defaults to 1.

maxZoom

number | undefined

Default: 3

Largest zoom. Defaults to 3.

defaultZoom

number | undefined

Default: 1

Initial zoom. Defaults to 1.

disabled

boolean | undefined

Default: false

Disable every interaction.

labels

PimoluImageCropperLabels | undefined

No default extracted.

Localizable labels.

className

string | undefined

No default extracted.

Class applied to the cropper wrapper.

Accessibility

  • Provide keyboard-operable crop controls and a non-drag alternative for essential image tasks.
Read the accessibility guide →