All components (244)

Crop image

Management · ImageCropper · .amset-cropper

What it is and when to use it

Crop an image: a box over the image that moves and resizes, free or with a fixed aspect ratio.

When to use it

A product photo, a cover or an avatar that has to come out with a specific framing and ratio.
It hands out the crop in pixels of the original image (x, y, width, height) through onChange: actually cropping, on the server or in a <canvas>, is the application's job.
aspects are the ratios offered besides "Free" (1:1, 4:3 and 16:9 by default); an empty list leaves only the free crop.
If the original size is known, naturalWidth and naturalHeight avoid waiting for the image to load.

When not to

Seeing an image enlarged: ImageViewer. Comparing two: ImageCompare.

Keyboard: the crop box receives focus; the arrows move it and Shift with the arrows resize it, one hundredth of the width at a time.

Accessibility: the box is a named slider that says its size and position in pixels, and carries the explanation of its keyboard.

Fine appearance: --amset-cropper-shade (what stays outside the crop), --amset-cropper-handle (the corner) and --amset-cropper-max-height.

What it looks like

Free1:14:316:9

Zoom: 100 %

Arrows to move the crop; Shift and arrows to resize it.

Move the box to crop.

<ImageCropper
  src={cartel}
  alt="Fall collection poster"
  naturalWidth={640}
  naturalHeight={360}
  zoomable
  rotatable
  onChange={(zona) => guardarZona(zona)}
/>

Props

Import it with import { ImageCropper } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`alt`required	`string`	What the image shows. Required: it names the image and the crop.
`src`required	`string`	—
`aspects`	`readonly CropAspect[]`	The ratios offered, besides «Free». An empty list leaves only the free crop, without a selector.
`className`	`string`	Merged with the library classes; it does not replace them.
`crossOrigin`	`"anonymous" \| "use-credentials"`	To read an image from another origin in the `<canvas>`: the server has to send `Access-Control-Allow-Origin`.
`defaultAspect`	`string`	—
`defaultValue`	`CropRect`	—
`naturalHeight`	`number`	—
`naturalWidth`	`number`	The original size of the image, if known. Otherwise it is read when it loads.
`onChange`	`(rect: CropRect) => void`	—
`onCrop`	`(result: CroppedImage) => void`	Called with the already cropped image (a `Blob`) when "Crop" is pressed, which only appears if this is passed. It crops in the browser with a `<canvas>`: the image has to be from the same origin or come with permission (`crossOrigin`).
`outputType`	`"image/png" \| "image/jpeg" \| "image/webp"`	The format of the cropped image. `image/png` by default.
`quality`	`number`	The quality from 0 to 1 of the cropped image, in the formats that lose quality (`image/jpeg`, `image/webp`).
`rotatable`	`boolean`	Buttons to turn the image a quarter turn either way; the crop is made on the already turned image. Not by default.
`value`	`CropRect`	The crop, in pixels of the original image. If passed, whoever uses it controls it.
`zoomable`	`boolean`	Buttons to zoom the image in and out and crop more precisely (up to 4 times). Not by default.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-cropper-shade`	`var(--amset-overlay)`
`--amset-cropper-handle`	`0.875rem`
`--amset-cropper-max-height`	`28rem`

How to change it

.amset-cropper {
  --amset-cropper-shade: ...;
  --amset-cropper-handle: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: