This module adds a backend Char field widget that typeahead-fills the +field from a public @api.model method on the same model.
+Type in the field; after a configurable number of characters the widget +calls the method with the trimmed input, shows matching rows, and on +select writes the Char plus supported extra scalar and relational fields +that exist on the model and in the current view. min_symbols 0 +opens that list on focus and calls the method with False, so the +field can be used before any typing. See Usage for supported value +formats.
+Table of contents
+No configuration is required. Enable the module; consuming addons +declare Char fields and the method.
+To try the widget on a partner City field (Umbria cities), install +web_widget_autocomplete_demo.
+Use widget="autocomplete" on a fields.Char and name a public +@api.model method in options.
+The method receives the trimmed input string, or False when +min_symbols is 0 and the field is focused with an empty input, +and must return a list of dicts. Each dict’s keys are field names. The +widget field’s key is the label shown in the dropdown and the value +written to the Char. Any number of extra keys may be present; on +select they are written to sibling fields that exist on the model +and in the same view (visible or invisible). Keys missing from the +model or view, unsupported field types, and invalid values are skipped. +The id key is always ignored.
+Supported extra values (Python values are converted to JSON by the RPC):
+| Field type | +Value returned by the method | +
|---|---|
| Char, Text, HTML | +String; use an empty string to clear | +
| Integer, Float, Monetary | +A value convertible to a finite number, +as with the existing Integer behavior | +
| Boolean | +True or False | +
| Selection | +An exact selection key, or False to +clear | +
| Date | +"YYYY-MM-DD", or False to clear | +
| Datetime | +"YYYY-MM-DD HH:MM:SS" in UTC, or +False to clear | +
| Many2one | +A positive integer ID, +[id, display_name], or False to +clear | +
| One2many, Many2many | +A list of the ORM commands described +below | +
Invalid dates are skipped. Datetimes are converted from UTC to the +client timezone by Odoo. A bare Many2one ID is resolved through Odoo to +obtain its display name; the related record must exist and be readable +by the user.
+Supported x2many commands are (0, 0, values) to create a related +record, (4, id) or (4, id, 0) to link an existing record, and +(6, 0, ids) to replace the relation. For example, [(4, 12)] +links record 12 and [(0, 0, {"name": "Visit"})] creates a related +record. Create values must use the related model’s server-side field +formats.
+Replace removes relations omitted from the supplied IDs. In +particular, [(6, 0, [])] clears the relation; for One2many fields, +Odoo’s inverse field deletion policy can also delete removed records. An +empty command list [] makes no relation changes. Other opcodes and +malformed command shapes are rejected for that field as a whole. These +checks validate the payload format; the model method must enforce its +own authorization and Odoo access rights still apply when related +records are read or saved.
+Free typing (without selecting a row) updates only the Char. Extra +fields keep their previous values until the next select.
+A readonly extra is still filled in the UI on select. It is +persisted on save only if that field’s view node has force_save="1". +Without it, the fill is dropped on save with no error.
+The method must be publicly RPC-callable: not prefixed with _, not +@api.private, and decorated with @api.model so the first +argument is the search string rather than record ids. If the call fails, +the dropdown stays empty and an error notification is shown.
++<field + name="address_string" + widget="autocomplete" + options="{'function': 'address_auto_complete', 'min_symbols': 3, 'debounce': 5}" +/> +<field name="address_ref" readonly="1" force_save="1"/> +<field name="city" invisible="1"/> ++
+@api.model +def address_auto_complete(self, value): + """Return autocomplete rows for ``value``. + + :param str | bool value: trimmed input, or ``False`` when ``min_symbols`` + is ``0`` and the input is empty + :return: list of dicts whose keys are field names on this model + :rtype: list[dict] + """ + return [ + { + "address_string": "string1", + "address_ref": 1, + "city": "Perugia", + }, + ] ++
| Option | +Type | +Default if omitted | +
|---|---|---|
| function | +str (method name) | +none — no RPC, Char still editable | +
| min_symbols | +int | +3 | +
| debounce | +int (ms) | +250 | +
min_symbols 0 opens the dropdown as soon as the field is +focused, before the user types. The method is called immediately with +False, so it can return the full list. Typing still sends the +trimmed string. The debounce applies to typing, not to that focus call.
+For a dropdown whose options are fetched once (or when a +depending_on context key changes), use +web_widget_dropdown_dynamic instead.
+Bugs are tracked on GitHub Issues. +In case of trouble, please check there if your issue has already been reported. +If you spotted it first, help us to smash it by providing a detailed and welcomed +feedback.
+Do not contact contributors directly about support or help with technical issues.
+The dropdown UI is Odoo Community web.AutoComplete +(addons/web/static/src/core/autocomplete/).
+This module is maintained by the OCA.
+ +
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose +mission is to support the collaborative development of Odoo features and +promote its widespread use.
+This module is part of the OCA/web project on GitHub.
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
+Perugia
", + price: 42.5, + currency_id: [1, "EUR"], + country_id: 1, + tag_ids: [[4, 2]], + line_ids: [[0, 0, {name: "Visit"}]], + }, + ]); + onRpc("web_save", ({args}) => { + const values = args[1]; + expect(values.amount).toBe(9.9); + expect(values.enabled).toBe(true); + expect(values.founded).toBe("1540-06-01"); + expect(values.visited).toBe("2026-09-18 12:30:00"); + expect(values.region).toBe("center"); + expect(values.description).toBe("Capital of Umbria"); + expect(values.notes).toBe("Perugia
"); + expect(values.price).toBe(42.5); + expect(values.currency_id).toBe(1); + expect(values.country_id).toBe(1); + expect(values.tag_ids).toEqual([[4, 2]]); + expect(values.line_ids[0][0]).toBe(0); + expect(values.line_ids[0][2].name).toBe("Visit"); + expect.step("saved"); + }); + const view = await mountAutocompleteForm( + "{'function': 'address_auto_complete'}", + EXTRA_FIELDS + ); + await typeAndWait("Per"); + await contains(".o-autocomplete--dropdown-item").click(); + await animationFrame(); + const field = findComponent(view, (c) => c instanceof AutocompleteField); + expect(field.props.record.data.country_id).toEqual([1, "Italy"]); + expect(field.props.record.data.founded.isValid).toBe(true); + expect(field.props.record.data.visited.isValid).toBe(true); + await contains(".o_form_button_save").click(); + await animationFrame(); + expect.verifySteps(["saved"]); + expect(field.props.record.data.country_id).toEqual([1, "Italy"]); + expect(field.props.record.data.tag_ids.currentIds).toEqual([2]); + expect(field.props.record.data.line_ids.records[0].data.name).toBe("Visit"); + }); + + test("invalid extra values are skipped while the label is selected", async () => { + onRpc("address_auto_complete", () => [ + { + address_string: "Perugia", + amount: "not a number", + enabled: "yes", + founded: "31/12/1999", + visited: "invalid", + region: "missing", + description: 42, + notes: [], + price: "invalid", + country_id: "Italy", + tag_ids: [[6, 0, "bad"]], + line_ids: [[0, 0, []]], + }, + ]); + patchUpdateSteps(); + await mountAutocompleteForm( + "{'function': 'address_auto_complete'}", + EXTRA_FIELDS + ); + await typeAndWait("Per"); + await contains(".o-autocomplete--dropdown-item").click(); + await animationFrame(); + expect.verifySteps(["update:address_string"]); + expect(".o_field_widget[name='address_string'] input").toHaveValue("Perugia"); + expect(".o_field_widget[name='amount'] input").toHaveValue("1.50"); + }); + + test("replace and clear relations and optional scalar values", async () => { + const view = await mountAutocompleteForm( + "{'function': 'address_auto_complete'}", + `
This module is a demo of the autocomplete Char widget +(web_widget_autocomplete) on the partner City field.
+Suggestions are an in-memory list of cities with ZIP codes: Umbria and +other well-known Italian cities first, plus a few famous world cities. +Focusing City shows the first five cities before any typing. +Selecting a suggestion fills City and ZIP. There is no HTTP +lookup.
+Table of contents
+Install this module. It has no settings of its own.
+The widget itself is provided by web_widget_autocomplete; see that +module for the function, min_symbols, and debounce options.
+Open a contact form and edit City. The first five cities appear as +soon as the field is focused. Type to narrow the list (try “Per”, “Rom”, +“Par”, or “cit”). Selecting a row writes the city name into City and +the matching ZIP into ZIP. You can still type a city that is not in +the list; that path does not change ZIP.
+Bugs are tracked on GitHub Issues. +In case of trouble, please check there if your issue has already been reported. +If you spotted it first, help us to smash it by providing a detailed and welcomed +feedback.
+Do not contact contributors directly about support or help with technical issues.
+This demo uses the autocomplete Char widget +(web_widget_autocomplete). The dropdown UI is Odoo Community +web.AutoComplete.
+This module is maintained by the OCA.
+ +
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose +mission is to support the collaborative development of Odoo features and +promote its widespread use.
+This module is part of the OCA/web project on GitHub.
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
+