How to use Autocomplete Form Types

Sylius provides ready-to-use autocomplete form types for selecting entities in the Admin panel. These types are built on top of Symfony UX Autocomplete and offer seamless integration with translatable Sylius resources.

Available Autocomplete Types

Sylius ships with the following autocomplete types:

Type	Entity
ProductAutocompleteType	Product
ProductVariantAutocompleteType	ProductVariant
ProductAttributeAutocompleteType	ProductAttribute
TaxonAutocompleteType	Taxon

Using Built-in Autocomplete Types

To use a built-in autocomplete type in your form:

<?php

declare(strict_types=1);

namespace App\Form\Type;

use Sylius\Bundle\AdminBundle\Form\Type\ProductAutocompleteType;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;

final class MyFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('product', ProductAutocompleteType::class, [
                'label' => 'app.ui.select_product',
            ])
        ;
    }
}

Selecting Multiple Entities

Enable multiple selection with the multiple option:

$builder->add('products', ProductAutocompleteType::class, [
    'label' => 'app.ui.select_products',
    'multiple' => true,
]);

Customizing via extra_options

All built-in autocomplete types support customization via extra_options. These options are passed through the AJAX request to the autocomplete endpoint.

Option	Description	Default
choice_label	Entity property to display as label	name (or fullname for Taxon)
choice_value	Entity property to use as value	entity ID
entity_fields	Non-translated fields to search in	['code']
translation_fields	Translated fields to search in	['name']

Changing the Display Label

$builder->add('taxon', TaxonAutocompleteType::class, [
    'label' => 'app.ui.select_taxon',
    'extra_options' => [
        'choice_label' => 'code', // Display code instead of fullname
    ],
]);

Customizing Search Fields

$builder->add('product', ProductAutocompleteType::class, [
    'extra_options' => [
        'entity_fields' => ['code', 'sku'],           // Search in code and sku
        'translation_fields' => ['name', 'shortDescription'], // Search in name and shortDescription
    ],
]);

Limitations of extra_options

The extra_options array is serialized and passed via URL to the autocomplete endpoint. This means only scalar values and arrays are supported.

If you need advanced customization like custom query filtering (filter_query), you must create your own autocomplete type.

Creating a Custom Autocomplete Type

For Translatable Entities

If your entity has translations (implements TranslatableInterface), extend TranslatableAutocompleteType:

<?php

// src/Form/Type/SupplierAutocompleteType.php

declare(strict_types=1);

namespace App\Form\Type;

use App\Entity\Supplier;
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_admin_supplier',
    route: 'sylius_admin_entity_autocomplete',
)]
final class SupplierAutocompleteType extends AbstractType
{
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'class' => Supplier::class,
            'filter_query' => function (QueryBuilder $qb, string $query, EntityRepository $repository): void {
                $qb->andWhere('entity.enabled = :enabled')
                   ->setParameter('enabled', true);
            },
        ]);

        $resolver->setDefault('choice_label', function (Options $options): string {
            return $options['extra_options']['choice_label'] ?? 'name';
        });
    }

    public function getBlockPrefix(): string
    {
        return 'app_admin_supplier_autocomplete';
    }

    public function getParent(): string
    {
        return TranslatableAutocompleteType::class;
    }
}

For Non-Translatable Entities

For entities without translations, extend BaseEntityAutocompleteType from Symfony UX:

<?php

// src/Form/Type/WarehouseAutocompleteType.php

declare(strict_types=1);

namespace App\Form\Type;

use App\Entity\Warehouse;
use Doctrine\ORM\QueryBuilder;
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_admin_warehouse',
    route: 'sylius_admin_entity_autocomplete',
)]
final class WarehouseAutocompleteType extends AbstractType
{
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'class' => Warehouse::class,
            'filter_query' => function (QueryBuilder $qb, string $query): void {
                $qb->andWhere('entity.active = :active')
                   ->setParameter('active', true);
            },
        ]);

        $resolver->setDefault('choice_label', function (Options $options): string {
            return $options['extra_options']['choice_label'] ?? 'name';
        });

        $resolver->setDefault('searchable_fields', function (Options $options): array {
            return $options['extra_options']['searchable_fields'] ?? ['name', 'code'];
        });
    }

    public function getBlockPrefix(): string
    {
        return 'app_admin_warehouse_autocomplete';
    }

    public function getParent(): string
    {
        return BaseEntityAutocompleteType::class;
    }
}

Note: If you don't use autowiring and autoconfiguration, register your form type manually:

# config/services.yaml
services:
    App\Form\Type\WarehouseAutocompleteType:
        tags: ['form.type']