How do I use the #autocomplete_route_name property?

Question

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?

Answer 1

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.

Answer 2

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