Image Cropping

The crop editor is the same unified modal everywhere it appears. What differs is where the saved crop ends up, and that depends on how you opened the editor. See also Focus Point for how focus affects auto-generated crops and preset positioning.

Where the crop editor opens from

There are three entry points:

1. Asset detail page: the Crop image button in the Actions panel. Use this to build a reusable crop that any field can pick from the picker. See Asset Detail Page.
2. Card "Crop image" icon on a MediaHub field: the small crop icon on an asset card in the page editor. Opens the editor freeform (no fixed ratio) so you can pull any rectangle out of the image.
3. Inline crop preset badge on a MediaHub field: clicking a badge like 1:1 or 16:9 on a card opens the editor with that preset pre-selected, ready for a per-page-per-preset adjustment. See Adding to Templates → Inline crop badges.

The editor UI

The editor opens in a full-window modal:

• Sidebar (when relevant): every preset configured for this site, grouped if you've assigned groups in Configuration. Freeform is always at the top. The sidebar appears when you are choosing a preset to crop with; it stays hidden when you are adjusting an existing crop or editing focus only.
• Crop area: the source image with a draggable crop boundary. A faint rule-of-thirds composition grid is drawn inside the boundary. The eight resize handles on the corners and edges are sized for easy targeting on dense images and high-DPI displays. Toggle Focus in the toolbar to show or hide the focus point marker while you work.
• Action bar: Save as crop, Save as new asset, and Cancel sit at the bottom of the modal.

Picking a preset in the sidebar updates the crop boundary's aspect ratio and positions the initial selection around your focus point when one has been moved from centre. Picking Freeform removes the constraint so you can drag any rectangle.

Save options

The action bar at the bottom of the modal shows two save buttons: Save as crop and Save as new asset. They produce different outcomes.

	Save as crop	Save as new asset
What it creates	A crop page linked to the source asset	A standalone Library asset (a new top-level page in the library)
Linked to source	Yes. Alt text, labels, and the About note are inherited from the parent asset.	No. The new asset has its own metadata, independent of the source.
Where it appears	The asset's Crops section, or against the page+field (depending on context, see below)	In the Library, plus added to the current MediaHub field as a new card
Use it when	You want a reusable variant of the same image (a square version, a 16:9 hero crop, a portrait alt of a landscape).	The cropped result is conceptually a different image (a single portrait pulled from a group shot, or a product detail pulled from a wide product photo) and deserves its own alt text and metadata.

Save as crop: which scope?

"Save as crop" can produce either a library crop (visible in the asset's Crops section, included in crops() and cropCount(), and selectable in the picker) or a field-level crop (scoped to one page+field combination, used only to fill a preset badge on that card). Which one you get depends on how you opened the editor:

• From the asset detail page: always library-scoped. There's no page or field in scope to scope it to.
• From a card's "Crop image" icon (freeform): library-scoped. A freeform crop has no preset badge to fill, so it's saved as a library crop on the source asset.
• From an inline preset badge (e.g. clicking the 1:1 or 16:9 badge): field-scoped. The crop is tied to this specific page and field combination, so the same badge on a different page can have its own positioning. Field-scoped crops do not appear in the asset's Crops table or in the picker; they fill the badge only.
• From a card's "Crop image" icon, with a preset selected inside the editor: library-scoped. The freeform entry point overrides the preset choice for scoping purposes because there's no badge in play.

For the full library-vs-field-level model, see Crops API → Library crops vs field-level crops.

Save as new asset

"Save as new asset" creates a fresh top-level asset in the Library, copies the cropped pixels into its own file directory, and (if you opened the editor from a field) adds it to that field as a new card. The new asset is independent of the source: editing its alt text, labels, or About note has no effect on the source asset, and vice versa. The source asset is unchanged either way.

Use this when the cropped result is conceptually a different image, not just a reframe of the original. A portrait pulled from a group shot wants its own alt text describing one person, not the whole group, so it makes sense as its own Library asset.

Save confirmation

After a successful save, a notification tells you where the crop went:

• Crop saved to "[Asset Title]": library-scoped. Open the source asset's detail page to find the new crop in the Crops section.
• Crop saved for this field.: field-scoped. The preset badge on the card now shows the new crop. The crop won't appear elsewhere.

For "Save as new asset", the new card appears in the field immediately and the asset is also added to the Library.

Cancelling

The Cancel button closes the editor without saving. Adjustments to the crop boundary are discarded, and any pre-existing crops (library or field-scoped) are left untouched.

Adjusting an existing crop

Saved library crops are listed in the Crops section of the asset detail page. Clicking the info icon on any crop opens a detail panel showing its preset, dimensions, file size, filename, creation date, and the raw crop coordinates. The panel has an Adjust Crop button that re-opens the crop editor with the original selection pre-loaded, so you can reposition or resize without starting from scratch.

Field-level crops are adjusted by clicking the corresponding preset badge directly on the card in the page editor. The badge is filled the moment the page editor renders, so you don't need to "create" the crop first; clicking it always opens the editor on the current selection.

Cascade delete

Deleting an asset from the Library permanently removes all of its associated crop pages, both library and field-level. The delete confirmation on the asset detail page shows how many crops will be removed.

What about resizing or other adjustments?

The editor handles cropping only in this version. A broader "variations" workflow covering resizing and image adjustments is on the roadmap. For now, resizing is handled at output time through ProcessWire's standard $image->size() API, or by passing dimensions to cropImage() and ensureCropImage(). See Crops API.