Crop Tool

Configure the Crop tool with config.crop — the aspect-ratio grid, the resize presets, and which controls appear. Every field is optional; omit crop entirely to ship the full built-in tool.

When to use this

Your output must match a fixed set of formats (social sizes, print, avatars).
You want on-brand ratio labels ("Square", "Widescreen") instead of raw numbers.
You need named, one-click resize targets so exports land on exact dimensions.

Config reference

Option	Type	Default	Description
`aspectRatios`	`AspectRatioPreset[]`	built-ins	Full custom ratio list for the Aspect Ratio tab.
`presets`	`string[]`	all	Whitelist of ratio ids to show, in order. Filters `aspectRatios`.
`allowCustomRatio`	`boolean`	`true`	Allow a free, unconstrained crop. Set `false` to force a fixed ratio.
`showRotateFlip`	`boolean`	`true`	Show the rotate / flip cluster in the crop contextual bar.
`resizePresets`	`ResizePresetGroup[]`	—	Grouped size presets for the Resize tab.

Aspect ratios

Define the ratios in the Aspect Ratio tab with config.crop.aspectRatios. Each entry is a { id, label, ratio } object, so you can add fully custom ratios — not just the built-ins.

<ImageEditor
  src="/photo.jpg"
  config={{
    crop: {
      aspectRatios: [
        { id: "free", label: "Free", ratio: "free" },
        { id: "original", label: "Original", ratio: "original" },
        { id: "1:1", label: "Square", ratio: 1 },
        { id: "16:9", label: "Widescreen", ratio: 16 / 9 },
        { id: "2.39:1", label: "Cinema", ratio: 2.39 },
      ],
    },
  }}
/>

Field	Type	Description
`id`	`string`	Stable identifier used to track the active selection.
`label`	`string`	Text shown under the ratio icon.
`ratio`	`number \| "free" \| "original"`	`width / height` as a number, `"free"` (unconstrained), or `"original"` (the source image's own ratio). Omitting it behaves like `"free"`.

Omit aspectRatios to show the built-in ratios — free, original, 1:1, 4:3, 3:4, 16:9, 9:16.

To simply narrow or reorder the built-ins without redefining them, pass config.crop.presets — an array of preset ids. It filters whichever list aspectRatios provides, in the order you list them.

<ImageEditor src="/photo.jpg" config={{ crop: { presets: ["1:1", "4:3", "16:9"] } }} />

Open the Crop tool — only the curated ratios appear:

Loading image...

Resize presets

Add ready-made output sizes with config.crop.resizePresets. Each group appears under the Crop tool's Resize tab so users can resize to an exact target in one click.

<ImageEditor
  src="/photo.jpg"
  config={{
    crop: {
      resizePresets: [
        {
          label: "Social",
          presets: [
            { label: "Square", width: 1080, height: 1080 },
            { label: "Portrait", width: 1080, height: 1350 },
            { label: "Story", width: 1080, height: 1920 },
          ],
        },
      ],
    },
  }}
/>

Field	Type	Description
`ResizePresetGroup.label`	`string`	Group heading in the Resize tab.
`ResizePresetGroup.presets`	`ResizePreset[]`	The sizes in the group.
`ResizePreset.label`	`string`	Name shown on the preset button.
`ResizePreset.width`	`number`	Target width in pixels.
`ResizePreset.height`	`number`	Target height in pixels.

The first three presets in a group show up front, with a More toggle for the rest.

Open Crop → Resize to see the configured presets:

Loading image...

Crop controls

Three booleans gate the interactive controls around the crop. All default to true.

allowCustomRatio — when true, users can crop to any free, unconstrained shape and unlock the width/height fields. Set it to false to force a fixed ratio: free/unconstrained presets are dropped from the ratio grid, the width/height lock stays engaged (and its toggle is hidden), and the active preset is snapped to the first constrained ratio.
showRotateFlip — controls the rotate / flip cluster in the crop contextual bar above the canvas. Set it to false to hide those buttons.

<ImageEditor
  src="/photo.jpg"
  config={{
    crop: {
      allowCustomRatio: false,
      showRotateFlip: false,
    },
  }}
/>

Deprecated: crop.modes and crop.defaultMode are still accepted for type compatibility but are reserved / not implemented — the Crop tool has no mode switcher, so both fields are ignored.

Next steps

Customize the Toolbar — show only the tools you need.
Export & Save — pair resize with a fixed output format.
Configuration — the full config reference.

Verified by tests/guides/configure-crop.spec.tsx and tests/guides/configure-crop-ratios.spec.tsx in the @editx/image-editor package.