| name | add-autocomplete |
| description | Add an admin autocomplete form type for a Sylius Resource (translatable or not), optionally injected into another form via an extension |
| argument-hint | [ModelName] [TargetModelName] |
| allowed-tools | AskUserQuestion, Bash, Read, Edit, Write, Glob, Grep |
Add an Autocomplete Type for a Sylius Resource
This skill is for exposing a resource as an autocomplete in a form. For a grid filter, use ux_autocomplete / ux_translatable_autocomplete directly in the grid YAML (see /sylius-app:add-grid) — no custom form type needed.
Ask the user for:
- ModelName: the resource to make searchable (e.g.
Article)
- TargetModelName: the existing Sylius entity whose form should receive the field (e.g.
Product). Optional — skip steps 3–4 if not provided.
Read src/Entity/{ModelName}/{ModelName}.php to detect the entity's fields and whether it uses TranslatableTrait.
Prerequisites: /sylius-app:add-model (and /sylius-app:add-translatable-model if applicable) must have been run first.
Key rules
For translatable entities (uses TranslatableTrait)
- Use
TranslatableAutocompleteType as parent
- Always set
entity_fields: [] in extra_options — the default is ['code'], which crashes if the entity has no code field
- Set
translation_fields to the actual translated field names (e.g. ['title'])
- Set
choice_label directly via $resolver->setDefault('choice_label', fn(Options $options) => ...) — NOT inside extra_options
For non-translatable entities
- Use
BaseEntityAutocompleteType as parent
- Set
searchable_fields via $resolver->setDefault('searchable_fields', fn(Options $options) => [...])
Always
- Inject the model class via constructor (
%app.model.{model_snake}.class%)
- Register explicitly in
services.yaml with both form.type and ux.entity_autocomplete_field tags — PHP attributes alone are not enough without autoconfigure
filter_query is a PHP callable — it can NOT be passed via extra_options (only scalars/arrays travel via URL). Define it inside configureOptions instead.
1. Create the AutocompleteType
Translatable entity
src/Form/Type/{ModelName}/{ModelName}AutocompleteType.php:
<?php
declare(strict_types=1);
namespace App\Form\Type\{ModelName};
use Doctrine\ORM\QueryBuilder;
use Sylius\Bundle\AdminBundle\Form\Type\TranslatableAutocompleteType;
use Sylius\Bundle\ResourceBundle\Doctrine\ORM\EntityRepository;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\UX\Autocomplete\Form\AsEntityAutocompleteField;
#[AsEntityAutocompleteField(
alias: 'app_{model_snake}',
route: 'sylius_admin_entity_autocomplete',
)]
class {ModelName}AutocompleteType AbstractType
{
{
}
{
->([
=> ->{model_snake}Class,
=> [
=> [], // ⚠️ required entity has no field
=> [], // translated fields to search in
],
// filter_query must be defined here — NOT via (no callables via URL)
// => function (QueryBuilder , , EntityRepository ): {
]);
->(, function (Options ): {
[][] ?? ;
});
}
{
;
}
{
::;
}
}
Non-translatable entity
src/Form/Type/{ModelName}/{ModelName}AutocompleteType.php:
<?php
declare(strict_types=1);
namespace App\Form\Type\{ModelName};
use Symfony\Component\Form\AbstractType;
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\UX\Autocomplete\Form\AsEntityAutocompleteField;
use Symfony\UX\Autocomplete\Form\BaseEntityAutocompleteType;
#[AsEntityAutocompleteField(
alias: 'app_{model_snake}',
route: 'sylius_admin_entity_autocomplete',
)]
class {ModelName}AutocompleteType extends AbstractType
{
public function __construct(private readonly string ${model_snake}Class)
{
}
public function ():
{
->([
=> ->{model_snake}Class,
]);
->(, function (Options ): {
[][] ?? ;
});
->(, function (Options ): {
[][] ?? [];
});
}
{
;
}
{
::;
}
}
Replace {label_field} with the property used to display and search (e.g. title, name, code).
2. Register the service
Add to config/services.yaml:
services:
app.form.type.{model_snake}_autocomplete:
class: App\Form\Type\{ModelName}\{ModelName}AutocompleteType
arguments:
- '%app.model.{model_snake}.class%'
tags:
- { name: form.type }
- { name: ux.entity_autocomplete_field, alias: 'app_{model_snake}' }
3. Inject the autocomplete into the target form (optional)
If a TargetModelName was given, expose the autocomplete as a field on that Sylius form. Run:
/sylius-app:extends-form {TargetModelName} {model_snake}
Pass {ModelName}AutocompleteType as the field type when prompted. For ManyToMany relations, also pass multiple: true in the form options.
/sylius-app:extends-form handles the TypeExtension class, service registration, Twig template, Twig hook and translation.
4. Add the select_* translation
Get the project's default locale:
bin/console debug:container --parameter=kernel.default_locale
Add the placeholder label used by the autocomplete UI to translations/messages.{locale}.yaml:
app:
ui:
select_{model_snake}: 'Select a {ModelName}'
5. Clear cache
bin/console cache:clear
6. Verify
Known framework gotchas
| Symptom | Cause | Fix |
|---|
has no field named code | TranslatableAutocompleteType defaults entity_fields to ['code'] — most Sylius entities have a code, custom ones often don't | Set entity_fields: [] in extra_options |
| Empty results despite existing data | TranslatableAutocompleteType uses INNER JOIN on translations filtered by current locale — entities without a translation for that locale are excluded | Ensure entities have at least one translation in the active locale |
filter_query option has no effect when passed at usage | extra_options is serialized and sent via URL — only scalars and arrays are supported, PHP callables are not | Define filter_query inside configureOptions of your autocomplete type, never at usage site |
