Image Cropping
How the crop editor works: where it opens from, what each save option does, and where the result ends up.
The crop editor is the same unified modal everywhere it appears. What differs is where the saved crop ends up and what actions are available, and both depend on how you opened the editor. See also Focus Point for how focus affects auto-generated crops and preset positioning.
Crop scenarios
There are five entry points into the editor. Each determines what you see and what you can do:
| # | Where you are | What you click | What opens | Sidebar (presets) | Focus toggle | Available actions |
|---|---|---|---|---|---|---|
| 1 | Asset detail page | Crop (Actions panel) | Editor, create mode | Visible | Visible | Close, Save as new asset, Save as new crop |
| 2 | Asset detail page → Crops table | Adjust Crop on a crop row | Editor, adjust mode | Hidden | Hidden | Close, Save as new asset, Update crop |
| 3 | MediaHub field → master image card | Crop (card or drawer) | Editor, create mode | Visible | Visible | Close, Save as new asset, Save as new crop |
| 4 | MediaHub field → master image card | Crop badge (e.g. "Square") | Editor, adjust mode (if crop exists) or create mode (if missing) | Hidden (adjust) / Visible (create) | Hidden (adjust) / Visible (create) | Close, Save as new asset, Update crop / Save as new crop |
| 5 | MediaHub field → crop asset card | Crop (card or drawer) | Editor, adjust mode (against master image) | Hidden | Hidden | Close, Save as new asset, Update crop |
Scenario 5: crop assets placed into a field show a Crop button that opens the editor in adjust mode against the original master image.
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 in create mode when you are choosing a preset to crop with; it is hidden in adjust mode.
- 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.
- Focus toggle: visible in create mode so you can set the focus point before choosing a crop preset. Hidden in adjust mode to prevent accidental changes when the intent is only to reposition a crop.
- Action bar: the buttons at the bottom of the modal change depending on mode (see the table above). Close is always present.
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.
Action buttons
| Button | What it does |
|---|---|
| Save as new crop | Creates a new crop page under the master asset. Only available in create mode. |
| Update crop | Replaces the existing crop image in place. If the crop is library-scoped, the change applies everywhere that crop is used across the site. |
| Save as new asset | Creates a completely independent library asset from the current framing with no link to the original crop or master. The new asset appears in the Library and is added to the current field as a new card. |
| Close | Dismisses the editor. Focus point changes are already saved (they persist immediately via AJAX). Unsaved crop framing is discarded. |
Which crops are shared?
| Crop type | Created by | Scope | "Update crop" affects… |
|---|---|---|---|
| Library crop | Asset detail → Crop, or auto-generated on upload | Site-wide | Every page referencing this crop |
| Field crop | Inline badge click (named preset on a specific page+field) | Single page+field | Only that one field instance |
Crop assets placed directly into a MediaHub field (as cards) are typically library crops. Adjusting them via the field's Crop button updates the shared library crop.
For the full library-vs-field-level model, see Crops API → Library crops vs field-level crops.
Save confirmation
After a successful save, a toast notification appears inside the editor confirming 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.
For "Save as new asset", the new card appears in the field immediately and the asset is also added to the Library. Error toasts also appear inside the editor if something goes wrong.
Adjusting an existing crop
You can rename a crop's filename from the asset detail Crops panel or from the field edit drawer (blur or Enter). The crops table and any rich-text embed URLs stay in sync, the same as renaming a master asset.
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.
Crop assets in a MediaHub field have their own Crop button (on the card or in the drawer) that opens the editor in adjust mode against the master image.
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.
Developer reference
Two methods for working with crops in template code:
| Method | Behaviour |
|---|---|
cropImage('square', 400, 400) | Fetch-only lookup. Returns null if no crop exists for the given preset. |
ensureCropImage('square', 400, 400) | Lookup + auto-generate if missing. Always returns an image (except for freeform). Respects the focus point: auto-generated crops are centred on the focus area when one is set. |
See Crops API for the full method signatures, options, and usage examples.
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.
Last updated