Skip to content

Name Autocomplete Service

Service identity

  • Service ID: name.autocomplete
  • Interface: Drupal\name\Service\AutocompleteInterface
  • Class: Drupal\name\Service\AutocompleteService

This service resolves autocomplete suggestions for name components based on field configuration and available option sources.

Quick use

$autocomplete = \Drupal::service('name.autocomplete');
$matches = $autocomplete->getMatches($fieldDefinition, 'given', 'Jan');

Methods

getMatches(FieldDefinitionInterface $field, string $target, string $string): array

  • $target can be one component (title, given, family, and so on) or combinations such as name.
  • Returns key/value suggestion pairs suitable for JSON autocomplete responses.
  • Uses sources configured in field settings (options, stored values, taxonomy source values).

mapAssoc(array $values): array

Builds label => value pairs for autocomplete JSON from a flat value list.

findFieldValues(FieldDefinitionInterface $field, string $component, string $term, int $limit, string $mode = 'starts_with'): array

Queries stored field values the current user can view for the given component. Used by the autocomplete pipeline and available for custom controllers that reuse the same access rules.

Field settings

Autocomplete behavior is controlled by field storage settings on NameItem (see Field storage settings and NameFieldSettingsTrait). Relevant keys:

  • autocomplete_source — per-component checkboxes. Each component can enable one or more of:
  • title — title options list
  • generational — generational options list
  • data — stored values from existing content in the same field storage
  • autocomplete_separator — per-component separator override when editors type multi-component values (defaults to a single space when empty).
  • autocomplete_match — default match mode: starts_with (recommended) or contains.
  • autocomplete_match_overrides — optional per-component override of the default match mode.

At least one autocomplete source must be selected before a component can use the autocomplete field type. For admin-oriented guidance, see the name.autocomplete help topic.

Legacy stored value for generational source

Default field config may store the generational autocomplete checkbox as generation while the settings UI option key is generational. New saves use the UI keys; older sites may still have generation in config until field settings are re-saved.

Pipeline

AutocompleteService::getMatches() delegates to these @internal utilities:

  1. AutocompletePlanBuilder — normalizes field settings, resolves target components, and splits user input.
  2. AutocompleteMatcher — matches static sources (title options, generational options).
  3. AutocompleteFieldValueLookup — queries stored field values the current user can view.

See Classes and Interfaces for class references.

Injection example

use Drupal\Core\Field\FieldDefinitionInterface;
use Drupal\name\Service\AutocompleteInterface;

final class NameSuggester {

  public function __construct(
    private readonly AutocompleteInterface $autocomplete,
  ) {}

  public function suggest(FieldDefinitionInterface $field, string $input): array {
    return $this->autocomplete->getMatches($field, 'given', $input);
  }
}