MediaHub Feature Focus: Image Cropping in ProcessWire

How cropping usually works in ProcessWire

If you've used ProcessWire for any length of time, you'll be familiar with the image cropping workflow. You install a cropping module, configure your crop presets on a per-field basis, and editors crop images on each page individually. The cropped files are generated and stored in that page's assets directory.

This approach works well for many use cases. But it has a structural limitation: crops are tied to pages, not to images. If the same hero photo appears on 20 pages and each page needs a square crop, that's 20 separate cropped files on disk. Each crop is regenerated independently. There's no shared reference, and no single source of truth for that crop.

There's also the question of how crops are defined. With well-known ProcessWire cropping modules, you typically define crops by fixed pixel dimensions (e.g. landscape,900,600). This works, but it couples your crop definition to a specific output size rather than a flexible aspect ratio. And while these modules support crop badges on the page editor, they don't always make it clear at a glance whether a crop has actually been created or is still outstanding.

MediaHub takes a different approach entirely.

Crops as first-class assets

In MediaHub, a crop is not a derived file variation. It's a first-class ProcessWire page with its own ID, its own image file, its own metadata, and its own URL. When you crop an image in MediaHub, the result is a new page stored once in the centralised library, linked back to its parent asset.

This distinction has practical consequences. A crop page can be selected independently from any MediaHub field on any page. It can be queried with ProcessWire selectors. It has its own alt text (inherited from the parent asset). It supports every native ProcessWire image method because $crop->image() returns a standard Pageimage.

If 20 pages need a square crop of the same photo, that's one cropped file in the library referenced 20 times. Not 20 files.

Creating crops from the asset detail page

Every image in MediaHub has a detail page accessible from the library. The detail page shows the full image preview, file metadata, usage tracking, and an Actions bar with a Crop button.

Clicking Crop opens the crop editor. You select an aspect ratio preset from the panel, drag to position the crop area on the image, and save. The crop is created as a new page under the asset's crop collection, and a table on the detail page immediately reflects the new crop with its dimensions, file size, preset name, and a thumbnail.

This table is the connection point. You can see every crop that exists for an image in one place, click into any crop to inspect its coordinates and metadata, or create additional crops from the same source. The relationship between the parent image and its crops is always visible and navigable.

The crop editor: built-in and custom presets

MediaHub ships with nine built-in aspect ratio presets: Freeform, Original, Square (1:1), Widescreen (16:9), Portrait (4:5), Tall (5:7), Standard (4:3), Narrow (3:5), and Wide (3:2). These cover the most common web and social media ratios.

For project-specific needs, you can define custom presets in the MediaHub module configuration. Each custom preset has a human-readable label (shown in the crop editor), a key (used in template code), and a ratio in W:H format. Leave the ratio blank for an unconstrained freeform preset.

For example, a custom hero_banner preset with a 16:5 ratio gives editors a named, purpose-specific crop option that developers can reference in templates with $asset->cropImage('hero_banner'). The preset is available globally across every image in the library.

Selecting crops when adding images to a page

When an editor opens the MediaHub picker on a page, they're choosing from the full library of assets. But here's the key point: crops are selectable too. If an image has a square crop and a widescreen crop, all three items (the original and both crops) appear as individually selectable options.

This means a multi-value MediaHub field can hold the source image, a 16:9 crop, and a square crop as three separate, independently referenceable items. One page can select the square crop while another page selects the widescreen crop of the same source, with no extra file storage either way.

This is fundamentally different from per-page cropping modules where the crop is generated on the page and exists only in that page's context. In MediaHub, the crop exists in the library and is available everywhere.

Inline crop badges: the real highlight

Other ProcessWire cropping modules offer crop badges on the page editor too, and they configure crop options per field. MediaHub builds on this concept with two key additions: visual crop status and per-field badge selection from a shared preset library.

Each MediaHub field can be configured to display specific crop presets as status badges on each image card. You choose which presets appear on which field from a checklist in the field settings. A filled, coloured badge means the crop has been created. A hollow, dimmed badge means it hasn't been created yet. At a glance, an editor can see exactly which crops are done and which still need attention. Clicking any badge opens the crop editor pre-loaded with that preset, so the editor can create or update the crop without leaving the page.

This visual status layer is a meaningful difference. When you're managing a site with hundreds of pages and consistent crop requirements, being able to scan a page and immediately see "this hero image is missing its widescreen crop" saves real time. There's no need to click into each crop option to check whether it's been applied.

The per-field badge selection also means that if you have two MediaHub fields on the same page, say hero_image and sidebar_thumbnail, each field can show different badge presets. The hero field might display Widescreen and Square badges while the sidebar field shows only Square. Editors see exactly the crops relevant to each context.

Crop visibility in the media library

In the main MediaHub library grid, images that have crops display a small badge indicating the crop count. This gives administrators an at-a-glance overview of which assets have been cropped and which haven't, without opening each one individually.

When you need to audit crop coverage across your library, or when a client asks "have all the hero images been cropped for mobile?", the answer is visible from the library grid without clicking into individual assets.

Ratios, not pixels

Most ProcessWire cropping modules define crops by fixed pixel dimensions: landscape,900,600 or portrait,450,600. This ties your crop definition to a specific output size. If you later need the same aspect ratio at a different resolution, you need a new crop setting.

MediaHub defines presets by aspect ratio: 16:9, 4:5, 1:1, or any custom ratio you configure. The crop is created at the image's native resolution within that ratio. You then resize in your template code to whatever output dimensions you need. This keeps crop definitions flexible and decoupled from layout decisions that may change over time.

Putting it together: a real-world example

Consider a page template with three image contexts: a hero banner, an inline content image, and an author avatar. Each has different crop requirements.

• The hero image needs a 16:9 Widescreen crop for desktop and a Square crop for mobile
• The inline content image might need a 4:3 Standard crop
• The author avatar only needs a Square crop

With MediaHub, each of these is a separate field with its own badge configuration. The hero field shows Widescreen and Square badges. The avatar field shows only Square. The content image field shows Standard. Editors see exactly what's expected for each field, and the filled/hollow badge colours tell them instantly whether the work is done. Developers can rely on the right crops existing because the visual feedback keeps editors on track.

And because the crops are stored centrally, if the same staff headshot appears as an author avatar on 30 blog posts, the Square crop exists once. Not 30 times.

The developer API for crops

Accessing crops in template code is straightforward. The API follows ProcessWire conventions and returns standard objects you already know how to work with:

// Check if an asset has a specific crop
$asset->hasCrop('square');       // boolean
$asset->cropCount();             // total number of crops

// Get a crop image directly (returns Pageimage or null)
$image = $asset->cropImage('square');
$thumb = $asset->cropImage('square', 400);        // sized to width
$sized = $asset->cropImage('square', 400, 300);    // exact dimensions

// Prefer crop, fall back to original
$image = $asset->cropImage('hero_banner') ?? $asset->image()->size(1200, 400);
echo "<img src='{$image->url}' alt='{$asset->altText()}'>";

Because crops are pages, you can also work with the crop page object directly for full control:

$crop = $asset->getCrop('square');  // PkdMediahubCropPage
$crop->image();         // Pageimage with full PW image API
$crop->presetKey();     // "square"
$crop->cropData();      // ['x' => 92, 'y' => 184, 'w' => 706, 'h' => 706]
$crop->master();        // back-reference to the source asset

// Get all crops for an asset
$allCrops = $asset->crops();    // PageArray

Every crop image supports the full ProcessWire image API. You can call size(), width(), srcset(), and any other native method on a crop image exactly as you would on any other Pageimage.

Summing up

MediaHub's approach to cropping is built on a simple principle: a crop should be created once, stored once, and selectable anywhere. By treating crops as first-class pages in a centralised library, using ratio-based presets instead of fixed pixel dimensions, and giving editors clear visual status on every field, MediaHub brings a level of control and efficiency that traditional per-page cropping can't match.

This is one part of what MediaHub brings to ProcessWire. For the full picture, read the introductory overview, or browse the complete documentation.