contact_image

Odoo 19 gave the contact photo its own widget. contact_image extends the standard image field component and changes exactly two things, both about the empty state.

First, the fallback. The base image widget shows a placeholder frame when the binary field is empty. contact_image instead reads the field named by the preview_image option, avatar_128 on every core usage, and displays that. Because avatar_128 on partners and users is computed server side into the colored initials avatar when no photo exists, the form always shows something person-shaped rather than a gray frame.

Second, the controls. With no valid photo, the usual small pencil button is replaced by a centered Add Photo button laid over the avatar, and the overlay is dimmed to quarter opacity until you hover. With a valid photo, the widget behaves exactly like image: edit and clear buttons, upload dialog, the same option set.

Faces matter in a CRM. Teams recognize customers faster, pick the right John from a list, and trust records that look maintained. The obstacle was always the empty state: a database of gray placeholder frames looks abandoned, and nobody feels invited to click a tiny pencil icon.

This widget is Odoo's answer. Every contact shows the generated avatar from day one, so the database never looks empty, and the oversized Add Photo button turns uploading from a hidden feature into an obvious next step. If your company builds custom directory-style models, employees, members, drivers, tenants, reusing this widget plus a computed avatar field gives you the same polished behavior for free.

The core pattern, verbatim from the partner form

<field name="image_1920" widget="contact_image"
       options="{'preview_image': 'avatar_128', 'size': [130,130], 'img_class': 'rounded border'}"/>
<field name="avatar_128" invisible="1"/> <!-- Needed in contact_image widget -->

The invisible companion field is not optional decoration; it is what loads the avatar into the record data the widget reads.

Rounded user-form variant with zoom

<field name="image_1920" widget="contact_image"
       options="{'preview_image': 'avatar_128', 'zoom': true, 'size': [130,130], 'img_class': 'rounded-4'}"/>

Exactly what the base users form ships. img_class takes any CSS classes for the img element; it appears in no options panel and only in extractProps.

The fallback logic in getUrl is worth reading precisely, because it explains two behaviors people mistake for bugs. The override only kicks in when the main field is empty or the uploaded file failed validation. In that state it takes the preview field's value: if the record is saved, it builds a normal /web/image URL for it; if the value is an unsaved base64 payload, it embeds it directly as a data URL, hardcoded as PNG in 19.

Consequence one: a user who uploads a broken file does not get a broken frame, they silently fall back to their initials avatar plus the Add Photo button, and only the validation state knows anything went wrong. Consequence two: the widget never shows the base widget's static placeholder on contacts, because partners and users always have a computed avatar_128. On a custom model without such a computed field, the empty state shows nothing but the Add Photo button, which is your cue to add an avatar-style computed binary rather than to debug the widget.

The class getter adds opacity-100 opacity-25-hover while there is no valid image, producing the dimmed-until-hover effect, and the template moves the upload button from the frame's bottom edge to dead center. All of it is empty-state choreography; a filled photo renders through the parent class untouched.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. We read this widget's file on the public development branch at the time of writing, with the standard caveat that the branch is unstable and can change before release.

The registration and option set are unchanged, but the internals are reworked: the fallback reads the new structured binary value and detects the real image type from the file's magic bytes instead of assuming PNG, the empty-state layout moves from the button to a container class getter, and a ui service hook appears. A new test file also lands, a sign the widget is becoming a supported fixture. XML written for 19 keeps working; JavaScript patches will need review. We re-verify after release.