WooCommerce productafbeelding formaat: de drie formaten en hoe je ze echt aanpast

WooCommerce genereert drie afbeeldingsformaten voor elke productfoto die je uploadt, en maar twee daarvan zijn in het WordPress-beheer aan te passen. woocommerce_thumbnail is de afbeelding in het catalogusraster, woocommerce_single is de grote afbeelding op de productpagina, en woocommerce_gallery_thumbnail is het rijtje kleine thumbnails eronder. Je past ze aan via Weergave > Aanpassen > WooCommerce > Productafbeeldingen — en toont dat paneel wel een keuzelijst voor uitsnijden maar geen breedtevelden, dan heeft je thema de breedtes bewust in code vastgezet.

De drie formaten

Naam van het formaat	Waar het verschijnt	Uitsnijden	Aanpasbaar in de customizer
woocommerce_thumbnail	Winkelpagina, categorierasters, gerelateerde producten, cross-sells	Standaard hard vierkant uitgesneden	Breedte en verhouding
woocommerce_single	Hoofdafbeelding op de losse productpagina	Niet uitgesneden — oorspronkelijke beeldverhouding blijft	Alleen breedte
woocommerce_gallery_thumbnail	Klein rijtje onder de hoofdafbeelding van het product	Hard vierkant uitgesneden	Nee

Deze komen bovenop de standaardformaten van WordPress. Eén productfoto levert doorgaans thumbnail, medium, medium_large, large, de drie WooCommerce-formaten en mogelijk extra’s op die je thema via add_image_size heeft geregistreerd. Dat zijn heel wat bestanden per upload, en het verklaart waarom een import van 300 producten zo lang duurt.

De gallery-thumbnail is degene die mensen verrast: die heeft helemaal geen instelling in het beheer. Op een standaardinstallatie is het een klein vierkantje, van oudsher 100px, en het is het formaat dat het snelst zacht oogt op een retinascherm, simpelweg omdat het bestand echt minuscuul is.

Waar de instellingen werkelijk staan

Weergave > Aanpassen > WooCommerce > Productafbeeldingen geeft je drie instellingen:

• Breedte hoofdafbeelding — de breedte van woocommerce_single. De hoogte gaat automatisch, dus de oorspronkelijke beeldverhouding blijft behouden.
• Breedte thumbnail — de breedte van woocommerce_thumbnail.
• Uitsnijden van thumbnails — 1:1 (vierkant, de standaard), Aangepast (je typt een verhouding als 4:3) of Niet uitgesneden.

Let op wat ontbreekt: er is geen hoogteveld voor de catalogusthumbnail, omdat de hoogte uit de uitsnijverhouding volgt. En voor de gallery-thumbnail is er helemaal niets.

Voordat je iets wijzigt, helpt het om precies te zien welke afgeleiden een bepaald bestand oplevert — sleep een echte productfoto in de tool voor WordPress-afbeeldingsformaten en je krijgt de volledige lijst, inclusief of je bron groot genoeg is om elk formaat te vullen zonder op te schalen.

Waarom je catalogusafbeeldingen er verkeerd uitzien

De catalogusthumbnail wordt hard vierkant uitgesneden. Hard uitsnijden betekent dat WooCommerce een vierkant uit het midden van je foto neemt en de rest weggooit — er wordt niet geletterboxt en er wordt niets platgedrukt. Een productfoto van 2000x1200 wordt een plak van 1200x1200 uit het midden, die daarna wordt verkleind.

Prima voor een fles die pontificaal in het midden staat met ruimte eromheen. Een ramp voor:

• Lange producten (ski’s, kabels, gordijnroedes) — je ziet het middelste derde deel en verder niets
• Composities buiten het midden — het product schuift naar de rand van het beeld en wordt doormidden gesneden
• Foto’s waarin het artikel het beeld van rand tot rand vult — boven- en onderkant vallen weg
• Sfeerbeelden met het product in een hoek

Het gangbare advies is “zet het uitsnijden op Niet uitgesneden”. Dat werkt, maar wees eerlijk over de prijs: niet uitgesneden betekent dat elke thumbnail zijn eigen beeldverhouding houdt, dus een raster met foto’s in verschillende oriëntaties wordt visueel rommelig en de rijen lijnen niet meer uit, tenzij de CSS van je thema wisselende hoogtes aankan. De meeste thema’s gaan uit van vierkanten.

De betere oplossing, als je die kunt betalen, ligt bij de bron: standaardiseer op vierkante productfoto’s met het artikel gecentreerd en gelijke marges. Dan doet een vierkante harde uitsnede niets en wordt alles verderop voorspelbaar. De uitsnijinstelling aanpassen is de noodgreep; consistente bronbestanden zijn de echte oplossing.

Wanneer het thema de breedtes vastzet

Biedt je paneel Productafbeeldingen alleen het uitsnijden aan, dan heeft je thema vaste breedtes opgegeven toen het WooCommerce-ondersteuning aanmeldde:

add_theme_support( 'woocommerce', array(
    'single_image_width'    => 800,
    'thumbnail_image_width' => 400,
) );

Geeft een thema die waarden mee, dan haalt WooCommerce de breedte-instellingen uit de customizer en laat alleen de verhouding staan. Dat is geen bug en het thema doet niet vervelend — de CSS van de productlay-out is rond precies die pixelbreedtes gebouwd, en jou ze laten wijzigen zou het raster breken.

Je kunt ze vanuit de functions.php van een child theme overschrijven met de filter per formaat:

add_filter( 'woocommerce_get_image_size_single', function ( $size ) {
    $size['width']  = 1000;
    $size['height'] = '';
    $size['crop']   = 0;
    return $size;
} );

add_filter( 'woocommerce_get_image_size_gallery_thumbnail', function ( $size ) {
    $size['width']  = 150;
    $size['height'] = 150;
    $size['crop']   = 1;
    return $size;
} );

Hetzelfde patroon werkt voor woocommerce_get_image_size_thumbnail. Dit is trouwens ook de enige manier om de gallery-thumbnail te wijzigen, want die heeft geen interface.

Even de werkelijke prijs, ronduit gezegd: een vastgezette breedte overschrijven betekent dat het bestand dat WooCommerce genereert niet langer overeenkomt met wat de CSS van het thema verwacht. Meestal schaalt de afbeelding gewoon in de browser en ziet het er prima uit, omdat hij nu groter is dan het vak. Soms heeft het thema een container met vaste hoogte en krijg je letterboxing of overloop. Test op één product voordat je er 2.000 opnieuw genereert.

Formaten wijzigen betekent opnieuw genereren

Elke formaatinstelling geldt alleen voor nieuwe uploads. Bestaande producten blijven de bestanden serveren die bij hun upload zijn aangemaakt, dus er verandert niets zichtbaars tot je ze opnieuw opbouwt.

WooCommerce trapt een achtergrondtaak af zodra je de customizer opslaat. Bij een kleine catalogus is dat genoeg. Bij een grote hangt het ervan af of WP-Cron betrouwbaar afgaat, en in een winkel met weinig verkeer gebeurt dat vaak niet, waarna je met een half opnieuw opgebouwde bibliotheek blijft zitten. Doe het liever zelf:

wp media regenerate --yes

Alleen productafbeeldingen opnieuw opbouwen:

wp media regenerate --yes --post_type=product

Wil je de achtergrondtaak uit de weg hebben terwijl je het handmatig doet:

add_filter( 'woocommerce_background_image_regeneration', '__return_false' );

Twee dingen doet opnieuw genereren niet. Het verwijdert de oude bestanden niet — je uploadmap houdt elke wees uit de vorige instellingen, en die map groeit. En het kan geen formaat maken dat groter is dan je bron, want WordPress schaalt niet op. Zet je de breedte van de hoofdafbeelding op 1200 terwijl je productfoto’s 800px breed zijn, dan komt er geen bestand van 1200px; de browser krijgt een bestand van 800px en rekt het uit, en srcset heeft niets beters aan te bieden.

Het formaat dat je moet uploaden

Mik op vierkante bronbestanden op ongeveer twee keer je grootste ingestelde breedte — 1200x1200 voor een hoofdafbeelding van 600px, 1600x1600 als je thema 800px gebruikt. Dat dekt retinaschermen met 2x en geeft WordPress genoeg pixels om elke afgeleide te bouwen zonder op te schalen. Houd elk product op dezelfde afmetingen, zodat het raster gelijkmatig blijft.

Nog steeds vast?

Zijn de formaten juist ingesteld, heb je opnieuw gegenereerd en ziet een product er nog steeds verkeerd uit, open de afbeelding dan in een nieuw tabblad en lees de bestandsnaam. Een achtervoegsel met afmetingen die bij geen enkel door jou ingesteld formaat horen, betekent dat iets anders dat formaat heeft geregistreerd. Helemaal geen achtervoegsel betekent dat WooCommerce is teruggevallen op het volledige bestand, en dat wijst er bijna altijd op dat de bron te klein was voor het formaat dat je vroeg. Haal dat bronbestand door de tool voor afbeeldingsformaten en vergelijk wat WordPress zou moeten genereren met wat de browser werkelijk heeft geladen — wijken die af, dan zit er meestal een optimizer-plugin of een CDN met beeldverkleining tussen.