background_image

The employee form in Odoo does something subtle with photos: the picture you see in the header panel is not editable in place. Upload and removal happen through the standard avatar field elsewhere; the big display is background_image, a deliberately stripped-down cousin of the image widget.

The JavaScript is five lines: extend ImageField, point it at a different template, re-register. All behavior, options and even the zoom tooltip machinery are inherited. What changes is the template: instead of the image frame with its hover controls for uploading, editing and deleting, this one renders a single <img loading="lazy"> whose source is resolved by the inherited getUrl, honoring preview_image to serve a smaller variant.

The name comes from how HR uses it: the employee form styles the image as a full-bleed background panel behind the name block, and the org chart cards do the same. The widget itself does not apply any background positioning; that comes from the surrounding HR styles, which is worth knowing before borrowing it elsewhere.

The pattern this widget embodies matters more than the widget: separate where an image is managed from where it is displayed.

On the employee form, the photo appears twice: once as the editable avatar, once as the large panel. Making the large panel editable too would invite accidental drag-and-drop replacements and confuse whose photo pipeline (resizing, WebP variants) actually runs. The display-only copy costs nothing and cannot be broken by a user.

We reuse the same trick in client projects: product images on operational dashboards, site photos on field-service tasks, signatures on approval screens, anywhere staff must see an image but should never change it from that screen. Because it accepts a preview_image field, the display copy can also load a smaller resized variant instead of the full upload, which keeps image-heavy kanbans fast.

As the employee form uses it

<field name="image_1024" widget="background_image"
       options="{'zoom': true, 'zoom_delay': 1000, 'preview_image': 'image_128'}"
       class="d-block position-relative"/>

Displays the 128px variant for speed, zooms to the stored image on hover after one second.

A read-only product photo on an operations view

<field name="product_image" widget="background_image"
       options="{'preview_image': 'product_image_256'}"/>

Staff see the photo; nobody can replace it from this screen. Requires the hr module (or copying the five-line widget into your own).

Because everything is inherited, the sharp edges of this widget are actually the image widget's, and two of them bite harder here.

The many2one mode inherits its crash. The image field supports binary and many2one types, and for many2one it throws unless preview_image is provided, an inherited check that fires identically here. If you point background_image at a many2one, set preview_image to the image field on the target model or the view will not render.

Cache-busting still follows write_date. The inherited URL builder appends the record's write_date as a cache key (the descriptor even declares a write_date field dependency), so a photo updated through the editable avatar refreshes here on the next load without stale-cache tricks. On related fields pointing at another record, that key is skipped, which can leave a stale image until a hard refresh, again inherited behavior worth knowing when displaying images across models.

Empty values render the placeholder image, the standard gray silhouette from /web/static/img/placeholder.png, because the inherited getUrl falls back to it. There is no way to render nothing instead without an invisible condition on the field.

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

No changes: the source file on master is byte-identical to Odoo 19. Any evolution will come through the parent image widget it spreads, so watch that page's Odoo 20 section rather than this one. We re-verify against the shipped release.