Daniel Siepmann - Coding is Art

Blog Post

How to create TYPO3 Form select element with options selected from database

Published: , Updated:

Tested with TYPO3: 12 LTS, 11 LTS, 10 LTS, 8 LTS

Topics: typo3


TYPO3s new form framework allows to write custom form elements. This way you are able to define a new select element, based on the existing one, but filled with options fetched from database.

E.g. you want your user to select from sys_category or some other custom records. In this blog post I will show how to provide the necessary logic in a custom PHP class, how to register a new element extending the existing one and how to use this new element in your forms.

The following steps are necessary:

  1. Write custom element as PHP Class, extending base element.
  2. Define custom element as prototype in yaml-Configuration, which inherits existing configuration of a select.
  3. Use the new element in the form.

The PHP Class

As we want to provide custom functionality, we need to create a PHP Class which will contain this functionality. In our example we want to provide sys_category records based on a parent sys_category as possible options. Therefore we need to provide one option, the uid of the parent system category. Also we need to fetch the records from database using Doctrine and provide them as options for the element, e.g. select in our case.

The implementation is done with the following class:

namespace DS\ExampleExtension\Domain\Model\FormElements;

use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Database\Query\Restriction\FrontendRestrictionContainer;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Form\Domain\Model\FormElements\GenericFormElement;
use TYPO3\CMS\Frontend\Category\Collection\CategoryCollection;

class SystemCategoryOptions extends GenericFormElement
    public function setProperty(string $key, $value)
        if ($key === 'systemCategoryUid') {
            $this->setProperty('options', $this->getOptions($value));

        parent::setProperty($key, $value);

    protected function getOptions(int $uid) : array
        $options = [];

        foreach ($this->getCategoriesForUid($uid) as $category) {
            $options[$category['uid']] = $category['title'];

        return $options;

    protected function getCategoriesForUid(int $uid) : array
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)

        return $queryBuilder
                    $queryBuilder->createNamedParameter($uid, \PDO::PARAM_INT)

First of all we extend the setProperty method, which receives all options. If the current option is the configured systemCategoryUid, we hook into and add the options. In all other situations we just call the original method.

Based on the configured uid, we fetch the records from database in our getCategoriesForUid method.

Afterwards we iterate over the results and prepare them to be used by the select, therefore we need a label and identifier. We use the saved title and uid. The result is set as the options for select element.

The class itself does not contain any relation to the specifics of a select-element. It should also be possible to use the same code for radio or checkboxes, as long as they make use of the options property.

Define custom element

Once our functionality is provided, we need to create a new form element to be available to our forms. Therefore we define the new element:

                10: 'TYPO3.CMS.Form.prototypes.standard.formElementsDefinition.SingleSelect'
              implementationClassName: 'DS\ExampleExtension\Domain\Model\FormElements\SystemCategoryOptions'
                templateName: 'SingleSelect'

On line 7 we define the identifier of our new element, under which we can use the element in our forms. We inherit the existing configuration of the select element and exchange the concrete php class for implementation. As the path of fluid template is generated from the name, we define to use the same template as for the select element.

That’s all we have to do, to define a new select with different implementation.

Use element

We are now able to use the defined element in our forms:

type: Form
identifier: Example
label: 'Example - Form'
prototypeName: standard
  submitButtonLabel: Submit
    type: Page
    identifier: page1
      previousButtonLabel: 'previous page'
      nextButtonLabel: 'next page'
        type: SingleSelectWithSystemCategory
        identifier: jobTitle
        label: Job Title
          systemCategoryUid: 5
          prependOptionLabel: 'please choose'
            required: required
            identifier: NotEmpty

We define our own SingleSelectWithSystemCategory element to be used and define our systemCategoryUid to be used. Everything else is exactly the same as for any other select, as we use the same template.


File Collection example

I was able to build another example, thanks to our customer werkraum_media, following the same approach to use a selected File Collection instead. The concept is the same, you can have a look at the code at:

Further reading

Check out the official doc sections: