# How to create a custom Autocomplete using the Drupal 8 Form API

> Here I will try to expose you a step by step guide which explains how you can create a custom Autocomplete field using the Drupal 8 Form API Core feature – An autocomplete that you could use in your own Drupal frontend applications.

Source: https://antistatique.net/en/blog/how-to-create-a-custom-autocomplete-using-the-drupal-8-form-api

Category: Development

# How to create a custom Autocomplete using the Drupal 8 Form API

Author(s)

[

![Kevin](https://images.statique.ch/t/w_750,h_750,c_fill,f_jpeg,q_70/wp/app/uploads/2020/12/Kevin-300x300.jpg)



](/en/agence/kevin)

[Kevin](/en/agence/kevin)10 July 2019

In this article, I will **not explain** how to [customise/alter an Autocomplete Field Widget](https://antistatique-website-2020.vercel.app/en/blog/how-to-create-a-custom-autocomplete-entity-field-widget-using-the-drupal-8-form-api) - which should only be used on from using the Drupal Admin UI.

Here I will try to expose you a **step by step** guide which explains how you can create a custom Autocomplete field **using the Drupal 8 Form API Core feature** - An autocomplete that you could use in your own Drupal frontend applications.

![gif autocomplete](https://images.statique.ch/t/wp/app/uploads/2020/12/autocomplete.gif)

If you are looking for resources which explains how to implement Views to alter an Autocomplete Field, please [refer to this excellent guide](https://www.drupal.org/docs/7/modules/entity-reference/using-a-view-to-display-the-elements-in-the-autocomplete-widget).

> “ Truth can only be found in one place: the code ”
> 
> Robert C. Martin
> 
> Clean Code: A Handbook of Agile Software Craftsmanship

## Step 1- The autocomplete form element

The other day, I was asked to create a custom Autocomplete for a project which uses a custom Form build using the Drupal 8 Form API.

At first sight, you may be interested to use the `#entity_autocomplete` field type - it seems exactly what you need. Unfortunately, this is not. Indeed, the `#entity_autocomplete` doesn't allow you any customisation.

So, you will need the old folk's `#textfield` and his cousin attribute `#autocomplete_route_name`

The `#autocomplete_route_name` attribute will allow you to define a route to handle the autocomplete business logic (data you will return given the user input).

You also may add the `#autocomplete_route_parameters` attribute, this one gives you the possibility to send a fixed unalterable parameter to your `#autocomplete_route_name`, you may use it to fix the number of results to return.

## Step 2 - Define autocomplete route

Now you know how to create the autocomplete form, but you will need a route to manage the logic which will fetch data & return them.

How? By simply adding the reference to the route — where data will get retrieved from — to your `my_module.routing.yml` file:

Be careful to use the same route name (here `my_module.autocomplete.articles`) in your previous `#autocomplete_route_name`.

Also, be sure to change permission according to your own needs.

## Step 3 - Add Controller and return JSON response

Now having a routing & a form, you have to define your custom controller, with the `handleAutocomplete` method.  
Well, it's precisely this method that makes sure that the proper data gets collected and properly formatted once requested by Drupal.

Let's dig deeper and see how we can precisely deal with specific JSON response for our `textfield` element.

-   Setup an `ArticleAutoCompleteController` class file under `my_module/src/Controller/ArticleAutoCompleteController.php`;
-   Then, extend the `ControllerBase` class and setup your handle method (in our case `::handleAutocomplete` see `my_module.routing.yml`);

That's **pretty much all the hocus-pocus that you need** to have an autocomplete based on a textfield of Drupal 8.

## Sources

For the most curious of you, here are some sources of additional information that inspired the creation of this article.

**Purushotam Rai** (24 November, 2016). Implementing #autocomplete in Drupal 8 with Custom Callbacks  
See on [https://www.qed42.com/blog/autocom...](https://www.qed42.com/blog/autocomplete-drupal-8)

**Stijn Berkers** (28 February, 2018). How to produce a custom auto-complete field in drupal 8  
See on [https://lucius.digital/en/blog/drupal...](https://www.lucius.digital/en/blog/drupal-module-conditional-redirect-released-on-drupal-org)

**Make me alive** (4 May, 2014). Adding autocomplete for text-field  
See on [https://drupal.stackexchange.com/…/..](https://drupal.stackexchange.com/)

**Stijn Berkers** (18 July, 2018). How to add autocomplete to text fields in drupal 8: defining a custom route  
See on [https://www.optasy.com/blog/how-add-autocom...](https://www.optasy.com/blog/how-add-autocomplete-text-fields-drupal-8-defining-custom-route)

## More articles

Author(s)

[

![Anthony](https://images.statique.ch/t/w_750,h_750,c_fill,f_jpeg,q_70/wp/app/uploads/2024/11/anthony-1-300x300.png)



](/en/agence/anthony-salamone)

[Anthony](/en/agence/anthony-salamone)28 September 2026

### [Smashing Conference Freiburg 2026](/en/blog/smashing-conference-freiburg-2026)

Back in Freiburg for Smashing Conference 2026: AI and design systems, deeply technical CSS and HTML, and more human talks about teams and mindset. Here's what we took away.

Back in Freiburg for Smashing Conference 2026: AI and design systems, deeply technical CSS and HTML, and more human talks about teams and mindset. Here's what we took away.

[

![Smashing Conference Freiburg 2026 poster](https://images.statique.ch/t/w_750,h_500,c_fill,f_jpeg,q_70/assets/blog/smashing-2026.png)



](/en/blog/smashing-conference-freiburg-2026)

Author(s)

[

![Akira](https://images.statique.ch/t/w_750,h_750,c_fill,f_jpeg,q_70/wp/app/uploads/2025/03/akira-small-300x300.jpg)



](/en/agence/akira-kamata)

[Akira](/en/agence/akira-kamata)22 July 2026

### [Making of : “La nuit des Losers”](/en/blog/making-of-la-nuit-des-losers)

lanuitdeslosers.ch, built fast: paper wireframes, a bold hand-drawn identity, then Claude Code to prototype and ship. A mouse-tracking hero animation, a bowling game made of sponsor logos, and a few bugs we’re keeping.

lanuitdeslosers.ch, built fast: paper wireframes, a bold hand-drawn identity, then Claude Code to prototype and ship. A mouse-tracking hero animation, a bowling game made of sponsor logos, and a few bugs we’re keeping.

[

![Making of : “La nuit des Losers”](https://images.statique.ch/t/w_750,h_500,c_fill,f_jpeg,q_70/wp/app/uploads/2026/05/La-nuit-des-Losers-Teaser-1-768x576.png)



](/en/blog/making-of-la-nuit-des-losers)

Author(s)

[

![Pierre](https://images.statique.ch/t/w_750,h_750,c_fill,f_jpeg,q_70/wp/app/uploads/2020/12/Pierre-300x300.jpg)



](/en/agence/pierre)

[Pierre](/en/agence/pierre)7 July 2026

### [Dark mode: necessity or trend](/en/blog/dark-mode-necessity-or-trend)

Nous faisons le tri entre idées reçues, réalités techniques et bonnes pratiques de design.

Nous faisons le tri entre idées reçues, réalités techniques et bonnes pratiques de design.

[

![Dark mode: necessity or trend](https://images.statique.ch/t/w_750,h_500,c_fill,f_jpeg,q_70/wp/app/uploads/2026/07/1-768x384.png)



](/en/blog/dark-mode-necessity-or-trend)
