filterable_selection

A selection field's values are defined once, on the model. But views often need less than the full list: the loyalty program form should not offer Gift Card and eWallet (those have their own menus), a payroll view should only offer the states that make sense in its context. Redefining the field per view is not possible; filtering the dropdown is, and that is precisely what filterable_selection does.

It extends the standard selection widget and overrides one getter, options, applying whichever filter option you passed. Everything else, the dropdown rendering, keyboard behavior, the kanban autosave the base widget applies, is inherited unchanged.

The subtle design decision in the source: whatever the filter says, the value currently stored on the record is always included. A record whose value was set before the filter existed, or set from another view, still displays correctly instead of rendering an empty dropdown, and the user can see what they are changing away from.

This widget solves a governance problem: one model serving several audiences.

Say your quality states are draft, internal review, customer review, approved and obsolete. The operator view should only let people move between draft and internal review; managers see everything. Same field, two views, two filters, zero Python. That is cheaper to build and to upgrade than duplicated fields or onchange guards, and the model's data stays uniform for reporting.

The whitelist_fname variant goes further: the allowed values can be computed per record. A program in use (the loyalty example: coupon_count != 0 makes the field read-only, and the blacklist trims the choices) or a workflow whose next legal states depend on the current one can drive the dropdown from a computed field. That is a state machine enforced in the UI for the price of one compute method.

The honest caveat: this is UI-level filtering only. Records can still receive excluded values through imports, RPC or other views, so anything compliance-critical needs a Python constraint as well.

Blacklist, as the loyalty app uses it

<field name="program_type" widget="filterable_selection"
       options="{'blacklisted_values': ['gift_card', 'ewallet']}"/>

Every program type except the two blacklisted ones is offered.

Whitelist for a restricted view

<field name="state" widget="filterable_selection"
       options="{'whitelisted_values': ['draft', 'internal_review']}"/>

Field-driven filter (Odoo 18+)

<field name="allowed_states" column_invisible="1"/>
<field name="state" widget="filterable_selection"
       options="{'whitelist_fname': 'allowed_states'}"/>

With a compute on the model:

allowed_states = fields.Json(compute="_compute_allowed_states")

def _compute_allowed_states(self):
    for rec in self:
        rec.allowed_states = ["draft", "internal_review"] if rec.is_operator_ctx else [s[0] for s in rec._fields["state"].selection]

The referenced field must be loaded in the view; invisible is fine.

The widget's history is a textbook example of how Odoo promotes patterns from app to core.

In Odoo 16 it lived inside the loyalty module, built for exactly one job: keeping Gift Card and eWallet out of the program type dropdown. Odoo 17 moved the file into web core unchanged, whitelist and blacklist only. Odoo 18 added whitelist_fname, the record-driven variant, and the 18 and 19 files are byte-identical. If you maintained a custom "restricted selection" widget, and most integrators have written one, every Odoo since 17 ships it natively.

Two inherited details from the base selection widget carry over and are easy to miss. First, in kanban views the base widget hardcodes autosave, so changing a filtered value on a kanban card saves the record immediately. Second, on many2one fields the base widget loads choices with a single cached name_search capped at the ORM's default 100 records, and the filter then applies on top of that cache; on large models the whitelist can silently miss records beyond the cap, so keep this widget on selection fields or small relations.

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 functional changes: the filter logic, all three options and their precedence are unchanged on master. The diff is the framework-wide migration to the new props-schema API (useProps with typed validators), which only affects JavaScript that spreads this component's props. We re-verify against the shipped release.