I created a custom form and I want add a "users" reference field.

I see here I must use the property autocomplete_route_name, but what value must I set?

$form['project']['users'] = array(
  '#type' => 'textfield',
  '#title' => t('choose users'),
  '#autocomplete_route_name' => 'user.autocomplete',

With the previous code, I get the following error:

Uncaught PHP Exception Symfony\Component\Routing\Exception\RouteNotFoundException: "Route "user.autocomplete" does not exist." at /var/www/drupal8/core/lib/Drupal/Core/Routing/RouteProvider.php

What is the correct code I should use?

2 Answers 2


Users are entities so they're treated generically. The route is system.entity_autocomplete, with some parameters, but you don't need to get your hands that dirty. You can use the "entity autocomplete" form element type instead, which should be as simple as:

$form['project']['users'] = array(
  '#type' => 'entity_autocomplete',
  '#title' => t('choose users'),
  '#target_type' => 'user',

It's derived from a TextField, so you can use all the usual properties. Examples do seem to be a little hard to find other than in the core files (it's early days), but you can see all the available properties the entity_complete adds in EntityAutocomplete::getInfo(), and how they're used within other methods of the class.

  • Thanks for your answer :) But i'm not sure this is the best way, use #autocomplete_route_name seems to be the simplest choice, but maybe i'm wrong. I wait a bit, if no body proposes another solution I accept yours :) Commented Nov 30, 2015 at 6:56
  • @user2137454 This answers your question, which was how to use the autocomplete. What you are asking in your comment is a different question; I am not sure we can answer about the best way, since that is subjective. We should need to see more of your code, and at the end it would still be a subjective choice.
    – apaderno
    Commented Nov 30, 2015 at 8:13
  • 2
    This is correct and while it is not the exact answer to what you wanted to know (that would be: use a route that exists. user.autocompletee was removed a while ago), this is definitely want you want to use. This takes a way a lot of work that you'd have to otherwise do yourself. It will validate and load the user for you. This the underlying API used by entity reference field's autocomplete widget and supports all the things that does (like limit by user roles or use a view for the suggestions).
    – Berdir
    Commented Nov 30, 2015 at 20:20

From the entity reference element

$element['#autocomplete_route_name'] = 'system.entity_autocomplete';
$element['#autocomplete_route_parameters'] = array(
  'target_type' => $element['#target_type'],
  'selection_handler' => $element['#selection_handler'],
  'selection_settings_key' => $selection_settings_key,

See http://cgit.drupalcode.org/drupal/tree/core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php

  • I tried this method, you literally have to copy a part of code from core, that generates $selection_settings_key to make it work
    – mevsme
    Commented Jul 28, 2022 at 16:28

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.