Using Drupal Entity Reference Autocomplete Fields Effectively
Drupal’s entity reference autocomplete widget lets editors find existing content, users, taxonomy terms, media items, or custom entities by typing part of a name. Instead of scrolling through a long select list, the editor enters a few characters and chooses a matching record from a suggestion list. The saved value is the entity ID, while the displayed label comes from the referenced entity.
This is useful for websites where relationships change regularly. A local business directory might link an article to a suburb, a council website might connect a page to a service category, and an Australian retailer might associate products with brands or suppliers. The widget keeps these relationships manageable while preserving Drupal’s structured content model.
| Requirement | Recommended configuration | Typical use |
|---|---|---|
| Select one existing item | Entity reference autocomplete | Author, suburb, brand, related page |
| Select several items | Autocomplete with unlimited cardinality | Related articles, service areas, speakers |
| Choose from a short fixed list | Select list | Statuses, states, small category sets |
| Find items using custom rules | Views-based entity reference selection | Published content filtered by type or field |
| Create a new related item while editing | Autocomplete plus inline entity form | Products, contacts, event speakers |
| Reference users or taxonomy terms | Entity reference field with suitable target type | Authors, topics, locations |
Understanding Entity Reference Fields
An entity reference field stores a relationship between two Drupal entities. For example, a field on an “Event” content type can reference a user as the event organiser, a taxonomy term as the event category, or another node as a related event. The referenced item is not copied into the host node; Drupal stores its identifier and loads the related entity when the page is rendered.
In current Drupal versions, this functionality is provided by the core Entity Reference module. The older name “Entity Reference” is still common in documentation and conversations, while the field type appears in the administration interface as “Entity reference”. Drupal also provides “Entity reference revisions” for relationships that need to point to a specific revision, especially with reusable paragraphs and editorial workflows.
The autocomplete widget is a form display setting, rather than a separate data type. A field can use the same entity reference storage while displaying as an autocomplete, select list, checkboxes, or another supported widget. This separation is important: changing the widget changes the editor experience, not the underlying relationship.
Creating The Field And Choosing A Widget
Go to Structure, select the relevant content type or entity bundle, and open Manage fields. Add a field with the Entity reference field type. Drupal then asks which entity type the field should target. Common choices include Content, User, Taxonomy term, Media, and any custom entity type supplied by a module.
Set the allowed number of values according to the relationship. “Limited” with a value of one creates a single reference, while “Unlimited” or a larger limit permits multiple selections. A field called “Related services” may allow several values, whereas “Primary contact” should usually allow one. Defining this accurately prevents editors from creating ambiguous relationships.
After saving the field, open Manage form display for the same bundle. Choose “Autocomplete” or “Autocomplete (Tags)” in the widget column, depending on the available Drupal version and field configuration. The standard autocomplete presents a suggestion for each entered value. The tags-style version is useful when editors need to add several references in one field and remove selected values individually.
The widget’s settings can include the minimum number of characters before suggestions appear, the number of results shown, and the amount of text retained before an autocomplete request is sent. A low minimum can generate unnecessary requests on a large site, while a high minimum can make short names difficult to find. A setting of two or three characters is often a practical starting point.
Configuring Selection Handlers And Results
The selection handler controls which entities can appear in the autocomplete results. For a content reference, the default handler may allow all nodes that the editor has permission to access. The configuration screen can often restrict results to selected content types, such as Articles, Basic pages, or Events. For taxonomy terms, you can limit the field to a particular vocabulary.
A Views-based selection handler is more useful when the default options are too broad. Create a view that lists the target entity type, add filters for publication status or bundle, and expose the view as an entity reference display. The field can then use that view as its source. This is a practical way to show only published events, active suppliers, current suburbs, or pages belonging to a particular section of a site.
The autocomplete label is normally generated from the entity label. For nodes, that is usually the title; for users, it is commonly the username or configured display name; for taxonomy terms, it is the term name. If several records have similar labels, editors may struggle to choose the correct one. A view can provide a more useful result label, such as “North Sydney — NSW” or “Springfield Primary Campus — Brisbane”.
Selection filtering must be designed with permissions in mind. Drupal should not expose entities that the current user is not allowed to access. Editors in Melbourne and Perth may see different results if the site has location-based access rules, and that can be expected behaviour rather than a fault. Test with the same roles used by content teams, not only with an administrator account.
Building A Useful Editorial Workflow
An autocomplete field works best when editors know what the relationship means. Use a field label such as “Service location” or “Related case study” instead of an internal label like “field_ref_02”. Add help text explaining whether the field expects a suburb, a council area, a person, or a page. On a large Australian organisation website, this distinction prevents editors from selecting a similarly named suburb in New South Wales when they intended one in Queensland.
Choose a consistent naming policy for referenced entities. If location terms use names alone, “Richmond” could refer to several places across Australia. Adding state abbreviations or another identifying value to the label makes autocomplete results clearer. The same principle applies to people with identical names, duplicated product titles, and annual events that recur each year.
The widget does not automatically create a missing entity. If an editor types a new suburb, supplier, or article title and submits the form without selecting a suggestion, Drupal normally treats that text as invalid. This is deliberate: it protects the database from accidental duplicate entities. Editors must create the referenced item first, or the site must provide an inline entity creation workflow through an appropriate contributed module or custom form.
For multiple values, teach editors to select each suggestion rather than typing a comma-separated list and moving on. The selected item becomes a token inside the field. This distinction matters because the autocomplete input is temporary text until Drupal resolves it to an entity ID.
Controlling Display And Access
The autocomplete field controls how editors select entities, but the field’s display settings control how visitors see the relationship. Under Manage display, configure the formatter for the target type. A content reference may display as a linked title, while a taxonomy term may appear as plain text or a link to its term page. Media references can use an image or media formatter, depending on the field’s purpose.
A reference to unpublished content can create confusing results. An editor may be able to select a draft, but anonymous visitors cannot open its link. In many cases, restricting the selection handler to published entities is safer. If the editorial process genuinely requires draft references, use a formatter and access configuration that do not expose private information or broken links.
Referenced entities retain their own access permissions. Removing a user’s access to a referenced node does not necessarily remove the relationship from the host entity; it changes whether that user can view or edit the target. Review this behaviour when using entity references for internal contacts, restricted documents, customer records, or information covered by Australian privacy obligations.
For performance, avoid presenting thousands of unrestricted results. A business directory covering Sydney, Melbourne, Adelaide, Perth, and regional areas can quickly produce a large result set. Limit the target bundle, require several characters before searching, and use indexed fields where possible. Editors get more relevant suggestions, and the server handles fewer autocomplete requests.
Troubleshooting Autocomplete Behaviour
When no suggestions appear, first check the field configuration and the selection handler. Confirm that matching entities exist, that they belong to an allowed bundle or vocabulary, and that the current user has permission to view them. Test a distinctive part of the label rather than a common word. A view display used for entity references must also be configured with the correct entity type and display plugin.
Browser developer tools can reveal JavaScript and network errors. Drupal sends an autocomplete request to a system route, and the response should contain matching values in the format expected by the widget. A JavaScript error from an unrelated theme script can stop the widget from behaving correctly. Clear Drupal caches after changing field, view, route, library, or theme configuration.
If the widget displays stale results, rebuild caches and check that the referenced entities are indexed or available to the selected handler. Search API configuration affects Search API views, but a standard entity reference autocomplete generally queries Drupal’s entity system or a configured view directly. Do not assume that rebuilding a Search API index will fix a misconfigured standard handler.
Long labels can make the result list hard to scan. Improve the entity label, add identifying fields to a custom view, or create a purpose-built selection handler. Avoid relying on CSS to hide important differences. Editors using a laptop in a busy office or a smaller screen in a regional site office still need enough information to select the correct record.
Extending The Widget In Custom Drupal Code
A custom module can alter the field widget or selection behaviour when configuration alone is insufficient. Form alters can change widget settings for a particular form, while a custom selection plugin can apply business rules that are difficult to express in a view. For example, a supplier reference might return only active suppliers assigned to the current purchasing region.
Custom code should validate the relationship on the server as well as filtering the autocomplete response. A user can submit a crafted request without using the visible form, so access checks and business rules must run when the entity is saved. Validate that the selected entity exists, is the correct bundle, is accessible to the current user, and is permitted for the current workflow.
Use Drupal’s entity and field APIs rather than writing entity IDs directly into database tables. The field item contains the target ID, and Drupal manages storage, translation, revisions, and cache metadata around it. When rendering referenced content programmatically, load the entity through the appropriate storage handler and respect access checks before displaying it.
For normal content administration, the core autocomplete widget is usually enough. Careful field naming, sensible selection filters, clear labels, and appropriate permissions produce a fast editorial experience without custom JavaScript. Whether the site manages council services in Canberra, event listings in Brisbane, or product relationships for an Australian online shop, the same structured reference makes connected content easier to maintain.