image_radio

Some choices are easier to make by looking than by reading. Picking a page layout, a course format or a template style is one of them: two words rarely convey what two thumbnails do instantly. image_radio exists for exactly that, and Odoo uses it in one place, the dialog where you choose whether a new course looks like a training or a documentation site.

It takes an ordinary selection field and renders each value as a picture. Clicking a picture writes that value. The selected one gets a highlight class, and the real radio inputs are visually hidden behind the images, so the control stays keyboard and screen-reader reachable while looking like a gallery.

The images are not stored on the record or derived from it. They come from an option on the field: a list of URLs, given in the same order as the field's selection values. That positional matching is simple and is also the source of most of the surprises described below.

Visual pickers earn their place at the exact moment a user is deciding something they cannot undo cheaply. A course layout, a website theme, a document template: getting it right first time avoids a rebuild. Two thumbnails do that job in a second, and the pattern generalizes to any onboarding step where a screenshot explains more than a sentence.

The cost is maintenance. The pictures live outside the data model, so a change to the selection values, or even reordering them, silently changes which image sits above which label. That is not a technical failure that raises an error; it is a wrong picture, which nobody notices until a customer picks the wrong option. Any project using this widget should treat the selection order as part of the design.

The core usage

<field name="channel_type" widget="image_radio"
       string="Choose a layout"
       options="{'images': [
           '/website_slides/static/src/img/channel-training-layout.png',
           '/website_slides/static/src/img/channel-documentation-layout.png']}"/>

Two selection values, two image paths, matched by position. This is the only place core uses the widget.

Serving your own images

<field name="template_style" widget="image_radio"
       options="{'images': ['/my_module/static/img/a.png',
                              '/my_module/static/img/b.png',
                              '/my_module/static/img/c.png']}"/>

Any URL the browser can fetch works, including an attachment route. Keep the array in the same order as the field's selection.

What breaks the mapping

# a padding entry is dropped before images are matched
style = fields.Selection([
    ('', ''),        # filtered out
    ('a', 'Alpha'),
    ('b', 'Beta'),
])

Values whose key and label are both empty are removed before the positional match, so an array written for the raw selection would be off by one.

The component does its work once, in setup. It reads the field's selection from the record's field definition, drops any entry whose key and label are both falsy, then maps what remains to triples of key, label and image, taking the image from the option array at the same index. Nothing re-runs that mapping later, so it reflects the selection as loaded.

Two details in the template are worth knowing before you use this widget twice on one screen. The radio inputs all carry the same hardcoded group name, and each input's id is the selection value itself. Put two image_radio fields on the same form and the browser treats every input as one radio group, so selecting a value in the second field visually clears the first, and the duplicate ids mean a label can point at the wrong input. Each field still writes its own value correctly, but the highlight is driven by the record rather than by the input state, so the visible result is confusing rather than wrong.

The other omission is read-only. The template never checks the read-only prop: the inputs render and the change handler writes, regardless of the record's state. On a form that is meant to be locked, hide the field rather than relying on read-only.

Finally, the highlight is a class comparison against the record's current value, not the input's checked state. That means the widget renders correctly after a server-side change, which is the upside of the same design that causes the group collision.

Odoo 20 is expected at Odoo Experience in Brussels, 24 to 26 September 2026. The development branch is unstable and can still change; we re-verify the page after the release.

No change. The component, the declared option, the positional matching, the hardcoded input group name and the missing read-only handling are all identical on the development branch, and core still uses the widget in the course creation dialog.