many2many

When a many2many field appears in a form without any widget attribute, this is what renders: X2ManyField, the embedded relational table registered under both one2many and many2many. It embeds a real list or kanban view of the linked records (the mode attribute picks which), with a pager, inline editing when the subview allows it, and an Add line.

The many2many personality differs from one2many in three ways, all in the source. First, Add opens a select and create dialog (titled Add: plus the field label) instead of a new inline row, and the dialog's search domain excludes records that are already linked. Second, removing a line calls forget, which drops the relation but never deletes the target record. Third, the Add button obeys the link option when present and only falls back to create.

The mode switch is a one line check: field.type === "many2many" || props.widget === "many2many". That second half means the widget name alone can force many2many behavior onto a one2many field.

The embedded table is where teams manage real relations: pickings in a batch transfer, badge ranks, tax documents. The unlink not delete semantics matter operationally, removing a picking from a batch must not delete the picking, and this widget guarantees that by construction.

The domain capable crud options are the governance tool. A rule like allow adding lines only while the parent is in draft is one option value, no code: options="{'link': [('state', '=', 'draft')]}". That keeps data discipline in the view layer where auditors can read it.

Studio applies this widget automatically; you never pick it by name:

1. Open the form in Studio.

2. Drag a Many2Many field from the component palette onto the form.

3. Choose the target model for the relation and save.

4. The field renders as this embedded table. Use the field's properties to disable creation or linking if needed.

Studio cannot express the domain form of the crud options; its toggles produce plain booleans only. Conditional rules like unlink only in draft still require editing the XML. Studio also cannot switch a one2many field into many2many behavior; that trick is XML only.

A standard many2many with linking restricted while draft, and creation disabled entirely:

<field name="tax_document_ids" widget="many2many"
       options="{'link': [('state', '=', 'draft')], 'create': False}"/>

The stock_picking_batch trick: a one2many field rendered with many2many behavior, so removing a picking unlinks it from the batch instead of deleting it:

<field name="picking_ids" widget="many2many" mode="list,kanban"
       readonly="state not in ['draft', 'in_progress']"/>

Renaming the Add line with the add-label attribute:

<field name="rank_ids" widget="many2many" add-label="Add a rank"/>

Details from the 352 line source that decide real world behavior:

The selection dialog excludes only saved links. The domain sent to the dialog filters out currentIds that are numbers, so records linked but not yet saved (virtual ids) are not excluded. In practice you will not see duplicates because saving normalizes the commands, but the search can transiently show a record you just linked.

write gates inline editing, and it is new in 19. The renderer receives readonly: props.readonly || !activeActions.write, so options="{'write': False}" (or a failing domain) makes embedded rows read only while still allowing link and unlink. The 18 source has no such gate.

Subview attributes AND with options. If the embedded list arch says create="false", no option can re enable creation; useActiveActions combines both and the stricter answer wins.

The list.many2many variant is a different component. In list view cells the registry serves ListX2ManyField, which prints formatX2many's plain text count (for example 3 records) and loads no subview at all. That is why a many2many column in a list view shows a count instead of tags unless you set widget="many2many_tags".

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

The crud options become attributes. On master, extractProps builds crudOptions with pick(attrs, "create", "delete", "link", "unlink", "write"); the options dictionary is no longer read. Every options="{'link': ..., 'create': ...}" on an x2many field will need rewriting as link="..." and create="..." attributes after the upgrade, across every custom view.

Kanban internals rename. The embedded kanban path switches from KanbanCompiler to CardCompiler as part of the framework wide kanban to card migration; XML using mode="kanban" is expected to keep working.

We will re verify this page against the released branch after the launch.