image

Anywhere Odoo shows a picture stored on the record, product photos, employee badges, event banners, this widget is rendering it. On an editable form it also carries the whole upload flow: pick a file, see it immediately, clear it, replace it.

Two abilities set it apart from a plain binary display. It can sit on a many2one and show an image from the related record, the pattern kanban cards use for the salesperson's avatar; the source enforces that usage by throwing an error unless preview_image names the related image field. And it detects the image type from the first character of the base64 payload, the magic-word technique, so JPEG, PNG, GIF, SVG and WebP all render without the record storing a mimetype.

Display is capped, not stretched: the size presets and width/height it derives set CSS max sizes, so images scale down to fit and never upscale past their pixels.

Images carry more purchase and recognition weight than any field type, and they are also the heaviest thing your database serves. This widget sits exactly on that trade-off, and its options are the knobs: size keeps list rows light, zoom gives buyers the detail view without a click, convert_to_webp cuts image weight by half or more at upload time rather than at page-serve time.

The WebP option deserves a business note on its own. Enabling it on product images means every upload lands with pre-generated smaller versions and report-safe JPEG copies. Websites get modern formats, PDF quotations keep working, and nobody runs a batch conversion later. For catalog-heavy shops this is the difference between a fast product page and a slow one, decided at data entry.

Our rule on implementations: set an explicit size in every list and kanban, enable zoom only where inspection matters (products yes, avatars no), and turn on WebP conversion for any model whose images reach the website.

Studio covers the common case fully.

1. Open the form in Studio and drag an Image field from the Add a field panel, or select an existing binary field and set Widget to Image.

2. In Properties, pick the display Size (Small, Medium, Large) and toggle Enable zoom as needed.

The interesting options stay in XML: convert_to_webp for the upload pipeline, preview_image for the many2one usage, accepted_file_extensions to restrict file pickers, and zoom_delay for hover timing. All are one-line additions shown below.

Product photo with zoom

<field name="image_1920" widget="image"
       options="{'size': [0, 270], 'zoom': True, 'zoom_delay': 300}"/>

Large preset with hover zoom after 300 ms. The zoom preview uses the full-resolution image.

WebP conversion at upload

<field name="image_1920" widget="image"
       options="{'convert_to_webp': True}"/>

JPEG and PNG uploads are converted in the browser; GIF, SVG and existing WebP pass through untouched, exactly as the source's exclusion list says.

Image from a related record

<field name="user_id" widget="image"
       options="{'preview_image': 'avatar_128', 'size': [0, 90]}"/>

A many2one rendered as the related record's image. preview_image is mandatory here; without it the widget raises an error rather than guessing.

Restrict what can be uploaded

<field name="logo" widget="image"
       options="{'accepted_file_extensions': '.png,.svg'}"/>

Enable convert_to_webp and the upload handler does far more than convert, all verified in the source.

The browser first re-encodes the file to WebP on a canvas (skipping GIF, SVG and files already WebP). Then, because reports cannot embed WebP, Odoo builds a ladder of derivatives: resized copies at 1920, 1024, 512, 256 and 128 pixels, each stored as an ir.attachment, and for every size a JPEG twin flagged format: jpeg for PDF use, with transparency flattened to white.

Practical consequences. One image upload can create ten-plus attachments, so attachment counts on media-heavy models are expected, not a bug. The JPEG twins are why quotations with WebP product images still print. And because conversion happens client-side, a very large source image costs the uploader's browser a moment, not your server.

Unrelated but equally invisible: URLs carry a unique token derived from the record's write_date, which the widget declares as a field dependency. That is why replacing an image updates everywhere immediately instead of fighting browser caches, and why the avatar cache-bust arriving for users in Odoo 20 already works here.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. The changes below are read from the public development branch and are not final until release.

Nothing changes for this widget. The development version of image_field.js declares the same seven options, the same alt attribute, the same many2one requirement and the same WebP pipeline. Internal component syntax moves to the new Owl props system, which affects JavaScript patches and nothing in XML. We re-verify once Odoo 20 ships.