handle

Every list in Odoo that users can rearrange by hand, sales order lines, project stages, product attribute values, has a column of drag dots on the left. That column is the handle widget on an integer field, almost always one named sequence.

The mechanics are simpler than they look. The widget renders nothing but the dots; the source component is a template with no logic of its own. When a user drops a row in a new position, the list view rewrites the integer values of the moved row and every row it displaced, then saves. The "order" is never stored as an order; it is just integers the list sorts by.

That is also why the source declares isEmpty: () => false and a fixed listViewWidth of 20 pixels: the column always renders, always tiny, whatever the value holds.

Manual ordering is one of those features nobody lists in requirements and everybody expects. Quotation lines must print in the order the salesperson arranged them. Manufacturing steps must appear in execution order. Pipeline stages must match how the team actually works, not alphabetical accident.

The handle widget is the difference between "drag it where you want it" and a support ticket asking why the quotation prints in the wrong order. On implementations we add a sequence field plus handle to almost every custom line model by default, because retrofitting user-controlled order after go-live means touching data, views and reports at once.

One process note: the order is data, not preference. When one user reorders lines, everyone sees the new order, including reports and the customer-facing PDF. Teams occasionally expect per-user ordering; that is a different feature entirely.

Studio can create the underlying field, but applying the handle widget itself is a view-XML step.

1. In Studio, add an Integer field to the line model and name it sequence (turn on developer mode first so you can set the technical name).

2. Set its default value so new rows land at the end, for example 10.

3. Exit Studio; the widget assignment (widget="handle") and the list ordering are added in the view XML as shown below.

Studio's widget selector does not offer Handle on integer fields, and Studio cannot set a list view's default_order. Both are one-line XML changes, which makes this a very small developer task rather than a Studio one. If drag ordering is on your wishlist, it usually rides along free with any other view work you commission.

The standard pattern

<list default_order="sequence">
    <field name="sequence" widget="handle"/>
    <field name="name"/>
</list>

Two requirements in two lines: the handle on the integer field, and the list ordered by that same field.

The model side

class QuoteLine(models.Model):
    _name = "my.quote.line"
    _order = "sequence, id"

    sequence = fields.Integer(default=10)
    name = fields.Char(required=True)

The id tiebreaker keeps rows with equal sequence values stable. The default of 10 means new rows append rather than jumping to the top.

Inside a one2many on a form

<field name="line_ids">
    <list editable="bottom" default_order="sequence">
        <field name="sequence" widget="handle"/>
        <field name="product_id"/>
    </list>
</field>

The same pattern works in embedded lists, which is where users meet it most: order lines, BoM components, checklist items.

Understanding what dragging actually writes saves debugging time later.

Dropping a row renumbers its neighbors. Odoo does not shift everything by one; it rewrites the sequence integers of the rows between the old and new positions. Expect several records in the write log from a single drag, and expect write-date and audit trails to reflect that.

Grouped lists constrain dragging. With grouping active you can reorder inside a group, and dragging between groups is either blocked or means something else (changing the grouped field), depending on the view. If users report "dragging stopped working", the first question is whether they grouped the list.

Automations fire. A drag is a write on the sequence field of several records. Automated actions or write overrides watching those models will trigger once per touched row, which matters if your automation is heavy or logs noisily.

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.

Nothing changes for this widget. The development version of handle_field.js is identical in behavior: same absence of options, same integer-only support, same 20px column. Only the internal component syntax moves to the new Owl props system, which affects JavaScript patches and nothing in XML. We re-verify this page once Odoo 20 ships.