popover_widget

Some rows in an inventory list need an explanation: this package is blocked, this move is late, this quantity is reserved elsewhere. The explanation is short, it only applies to some rows, and giving it a column would waste space on every row that does not need one.

This widget is Odoo's answer. It renders a small icon in the cell, and clicking it opens a popover with the explanation. Everything about that, the text, which icon, what color and which side the popover appears on, comes from a JSON string the server puts in the field.

Because the configuration travels with the data rather than living in the view, one column can show a red warning on one row, a blue information note on another, and nothing at all on a third. A row whose field is empty simply renders the icon with its defaults.

The value is contextual explanation without a column. On an inventory screen where a handful of rows have a problem, this is the difference between a list that flags its own exceptions and one that requires a report to interpret.

It is also a genuinely reusable building block for custom work. Any list where the server can decide that a particular row needs a note can use it: a credit hold on a customer, a certification expiring on an employee, a quality alert on a lot. The server writes the JSON, the view names the widget, and no client code is needed.

The one thing to plan for is the Odoo 20 icon change. Payloads that name Font Awesome icon classes today will need updating, and because the icon is data rather than view XML, the change is in your server code rather than in a view you can patch.

The core usage

<field name="json_popover" widget="popover_widget"
       nolabel="1" width="18px"
       invisible="not json_popover"/>

The narrow width and the visibility guard are part of the pattern: the column is a marker, not a data column.

A minimal payload

{
  "msg": "This package is blocked by a quality alert.",
  "color": "text-danger",
  "position": "right"
}

Written by the server into the char field. The icon falls back to the default information circle.

Your own popover template

{
  "popoverTemplate": "my_module.MyPopover",
  "lines": ["first", "second"],
  "icon": "fa-warning"
}

Any key beyond the documented ones, here the list of lines, arrives in the template as a prop.

The setup does four things and then stops. It parses the field value, falling back to an empty object if the field is empty or unset, reads the position out of it to configure the popover hook, and reads the color and icon with defaults. Everything else waits for a click.

Opening the popover passes the entire parsed object plus the record itself as props. That is what makes custom templates work: they receive whatever the server chose to include, and they can read the record too. It also explains why the widget declares its popover component's props as an explicit record entry plus a catch-all.

Parsing in setup rather than in a getter has the usual consequence. If the server recomputes the field while the row is on screen, the icon and popover keep the old payload until the component is recreated. On a list that reloads after each operation this is invisible; on a form that updates in place it is not.

The file is unusually explicit about being a base class. A comment at the top explains that to add behavior you extend both the popover component and the field, and set the new popover as the field's component. Several Odoo widgets do exactly that, which is why this one has more users than its single direct usage suggests.

The default icon is the one thing that moves in the next version. On the development branch both the documented default and the fallback in the code change from a Font Awesome class to a Material Symbols name, so a payload that passes an old style class will point at an icon that no longer exists.

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

The icon convention changes. The default icon becomes a Material Symbols name instead of a Font Awesome class, and the documentation comment is updated to match. Everything else, including the message, color and position keys and the pass-through of extra props, is identical.

Plan for your payloads. Because the icon is written by your server code rather than in a view, any custom module producing these payloads with Font Awesome class names has to be updated as part of the upgrade. Nothing will error; the icon will simply not render.