---
title: "Form.select ViewHelper <f:form.select>"
manual: "Fluid ViewHelper Reference"
version: "13.4"
permalink: "https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-select@13.4"
source: "Global/Form/Select.rst"
modified: "2026-09-17T09:07:45+00:00"
---

# Form.select ViewHelper `<f:form.select>`

ViewHelper which renders a `<select>` dropdown list for use within a form.

Go to the source code of this ViewHelper: [Form\\SelectViewHelper.php (GitHub)](https://github.com/TYPO3/typo3/blob/main/typo3/sysext/fluid/Classes/ViewHelpers/Form/SelectViewHelper.php).

> [!WARNING]
> **Attention**
>
> > [!NOTE]
> > **Changed in version 12.0**
> >
> > The f:form ViewHelpers can only be used within the Extbase context.
> >
> > In a non-Extbase context, for example within a
> > [FLUIDTEMPLATE](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/ContentObjects/Fluidtemplate/Index.html#cobj-template)
> > Use plain HTML `<form>` and `<input>` tags.

**Table of contents**

-   [Select field with hardcoded options](https://docs.typo3.org/permalink/t3viewhelper:select-field-with-hardcoded-options@13.4)
-   [Preselected field with options supplied by the controller](https://docs.typo3.org/permalink/t3viewhelper:preselected-field-with-options-supplied-by-the-controller@13.4)
-   [Select field for selecting (persisted) models](https://docs.typo3.org/permalink/t3viewhelper:select-field-for-selecting-persisted-models@13.4)
-   [Binding the select field to an object property](https://docs.typo3.org/permalink/t3viewhelper:binding-the-select-field-to-an-object-property@13.4)
-   [Working with options and option groups](https://docs.typo3.org/permalink/t3viewhelper:working-with-options-and-option-groups@13.4)
-   [Using an "Please select an option" placeholder](https://docs.typo3.org/permalink/t3viewhelper:using-an-please-select-an-option-placeholder@13.4)
-   [Arguments of the Form.select ViewHelper](https://docs.typo3.org/permalink/t3viewhelper:arguments-of-the-form-select-viewhelper@13.4)
-   [Arguments of the Form.select.option ViewHelper](https://docs.typo3.org/permalink/t3viewhelper:arguments-of-the-form-select-option-viewhelper@13.4)
-   [Arguments of the Form.select.optgroup ViewHelper](https://docs.typo3.org/permalink/t3viewhelper:arguments-of-the-form-select-optgroup-viewhelper@13.4)

## Select field with hardcoded options

Using the
[options](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-options@13.4)
parameter, you can pass a hardcoded array to the form.select ViewHelper.

The key of that array is used as option key, and the value is used as
human-readable name.

**Fluid**

**packages/my_extension/Resources/Private/Templates/User/GenderForm.html**

```html
<f:form action="selectGender">
    <f:form.select name="gender" options="{1: 'female', 2: 'male', 3: 'diverse'}" />
    <f:form.submit value="Submit"/>
</f:form>

```

**Controller**

The argument will have the key of the chosen entry as value.

**packages/my_extension/Classes/Controller/UserController.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class UserController extends ActionController
{
  public function genderFormAction(): ResponseInterface
  {
    return $this->htmlResponse();
  }
  public function selectGenderAction(int $gender): ResponseInterface
  {
    // do something
    return $this->redirect('show');
  }
}

```

## Preselected field with options supplied by the controller

Most options will be supplied by the controller. You can pass an associative
array with the options to the view:

**Fluid**

**packages/my_extension/Resources/Private/Templates/User/PaymentForm.html**

```html
<f:form action="selectPayment">
    <f:form.select name="payment" options="{paymentOptions}" value="{myPayment}" />
    <f:form.submit value="Submit"/>
</f:form>

```

**Controller**

The argument for the select field will have the key of the chosen entry as value.

**packages/my_extension/Classes/Controller/UserController.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class UserController extends ActionController
{
  public function paymentFormAction(): ResponseInterface
  {
    $paymentOptions =
        ['payPal' => 'PayPal International Services', 'visa' => 'VISA Card'];
    $this->view->assign('paymentOptions', $paymentOptions);
    $this->view->assign('myPayment', 'visa');
    return $this->htmlResponse();
  }
  public function selectPaymentAction(string $payment): ResponseInterface
  {
    // do something
    return $this->redirect('show');
  }
}

```

To pre-select a value, use the argument
[value](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-value@13.4).

## Select field for selecting (persisted) models

Consider we have the payment options from the previous example in the database
and in an Extbase model:

**Model**

**packages/my_extension/Classes/Domain/Model/PaymentMethod.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Domain\Model;

use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;

class PaymentMethod extends AbstractEntity implements \Stringable
{
  protected string $title;
  protected string $paymentIdentifier;

  // Getters and setters

  // If the model implement the __toString() method
  // The result of that method is displayed in the select form
  public function __toString(): string
  {
    return $this->title;
  }
}

```

**Controller**

In the controller we can get all payment methods from the
[Repository](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ExtensionArchitecture/Extbase/Reference/Domain/Repository/Index.html#extbase-repository)
now and pass it to the view as variable:

**packages/my_extension/Classes/Controller/UserController.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ResponseInterface;
use TYPO3\CMS\Extbase\Mvc\Controller\ActionController;

class UserController extends ActionController
{
  public function __construct(
    protected readonly PaymentMethodRepository $paymentMethodRepository,
  ) {}

  public function paymentFormAction(): ResponseInterface
  {
    $paymentOptions = $this->paymentMethodRepository->findAll();
    $this->view->assign('paymentOptions', $paymentOptions);
    $this->view->assign('myPayment', 'visa');
    return $this->htmlResponse();
  }
  public function selectPaymentAction(PaymentMethod $payment): ResponseInterface
  {
    // do something
    return $this->redirect('show');
  }
}

```

**Fluid**

The Fluid template can be left unchanged even though we are dealing with a
different data source:

**packages/my_extension/Resources/Private/Templates/User/PaymentForm.html**

```html
<f:form action="selectPayment">
    <f:form.select name="payment" options="{paymentOptions}" value="{myPayment}" />
    <f:form.submit value="Submit"/>
</f:form>

```

When the form gets submitted, the UID of the chosen model appears in the request
data. Extbase will then map that uid back to the model for you.

The ViewHelper will then use the model's UID as data submitted in the form and
the result of method `__toString()` as display text.

> [!NOTE]
> You can pass any array or `\Traversable` object to
> the [options](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-options@13.4)
> argument. This includes the result of `findBy()` methods on
> [Extbase repositories](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ExtensionArchitecture/Extbase/Reference/Domain/Repository/Index.html#extbase-repository),
> `QueryResultInterface` and objects
> stored as relation in another object as
> `ObjectStorage`.

### optionLabelField: Define another property of the model for the option label

If the model to be displayed has no `__toString()` method or you want to
display the content of a different field, use option
[optionLabelField](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-optionlabelfield@13.4)

```html
<f:form.select name="payment" value="{myPayment}"
    options="{paymentOptions}" optionLabelField="someLabel"/>
```

The [options](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-options@13.4)
may contain an array or anything else `Traversable` including

### optionValueField: Define another property of the model as value

If you are dealing with non-persisted models or Data-Transfer-Objects (DTO) there is
no valid identifier that could be used to automatically map the user's selection
in your controller. In this case, you must provide the name of the field to
be used to identify the object:

```html
<f:form.select name="payment" value="{myPayment}"
    options="{paymentOptions}" optionValueField="paymentIdentifier"/>
```

The controller action will then be called with the content of that field:

```html
// Variable $payment contains the paymentIdentifier from the model
public function selectPaymentAction(String $payment): ResponseInterface
```

## Binding the select field to an object property

When the surrounding `<f:form>` uses [Property mapping](https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-example-property@13.4)
we can also map the selected option to the model:

**Fluid**

**packages/my_extension/Resources/Private/Templates/User/PaymentForm.html**

```html
<f:form action="selectPreferredPayment" object="{user}" objectName="user">
    <f:form.select options="{user.availablePaymentOptions}"
                   property="preferredPayment"
    />
    <f:form.submit value="Submit"/>
</f:form>

```

**User Model**

The user model could have the following fields

**packages/my_extension/Classes/Domain/Model/User.php**

```php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use MyVendor\MyExtension\Domain\Model\PaymentMethod;
use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
use TYPO3\CMS\Extbase\Persistence\ObjectStorage;

class User extends AbstractEntity
{
  //Other fields
  protected ?PaymentMethod $preferredPayment;
  /** @var ObjectStorage<PaymentMethod>  */
  protected ObjectStorage $availablePaymentOptions;

  // initialize method, getters and setters
}

```

**Controller**

The controller action will then be called with the user object:

```php
public function selectPreferredPaymentAction(User $user): ResponseInterface
```

## Working with options and option groups

### Form.select.option ViewHelper `<f:form.select.option>`

ViewHelper for adding custom `<option>` tags inside a `<f:form.select>`.

Go to the source code of this ViewHelper: [Form\\Select\\OptionViewHelper.php (GitHub)](https://github.com/TYPO3/typo3/blob/main/typo3/sysext/fluid/Classes/ViewHelpers/Form/Select/OptionViewHelper.php).

The `<f:form.select.option>` ViewHelper can be used to create a completely
`<f:form.select.option>` `<option>`  tags in a way compatible with the
HMAC generation.
To do so, leave out the `options` argument and use child ViewHelpers:

**packages/my_extension/Resources/Private/Templates/User/OptionsForm.fluid.html**

```html
<f:form.select name="myproperty">
  <f:form.select.option value="1">Option one</f:form.select.option>
  <f:form.select.option value="2" selected="1">Option two</f:form.select.option>
</f:form.select>
```

> [!NOTE]
> Do not use HTML `<option>` tags!
> They will invalidate the HMAC generation!

### Form.select.optgroup ViewHelper `<f:form.select.optgroup>`

ViewHelper for adding custom `<optgroup>` tags inside a `<f:form.select>`, supports further child `<f:form.select.option>` tags.

Go to the source code of this ViewHelper: [Form\\Select\\OptgroupViewHelper.php (GitHub)](https://github.com/TYPO3/typo3/blob/main/typo3/sysext/fluid/Classes/ViewHelpers/Form/Select/OptgroupViewHelper.php).

The `<f:form.select.option>` can be grouped with the `<f:form.select.optgroup>`
to produce `<optgroup>` in the HTML output.

**packages/my_extension/Resources/Private/Templates/User/OptionsForm.fluid.html**

```html
<f:form.select name="myproperty">
   <f:form.select.option value="1">Option one</f:form.select.option>
   <f:form.select.option value="2">Option two</f:form.select.option>
   <f:form.select.optgroup>
      <f:form.select.option value="3">Grouped option one</f:form.select.option>
      <f:form.select.option value="4">Grouped option twi</f:form.select.option>
   </f:form.select.optgroup>
</f:form.select>
```

## Using an "Please select an option" placeholder

In HTML, the `<select>` element always selects the first option, if nothing
else is selected. If the field is mandatory and the user should be forced to
make a selection or if an empty value should be possible, you need an empty
option as first option. You can use the argument
[prependOptionLabel](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-prependoptionlabel@13.4)
to set a label for this object. The value of the option will be an empty string.
If you need another value, for example 0 because you are expecting an integer,
you can use
[prependOptionValue](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-prependoptionvalue@13.4).

**packages/my_extension/Resources/Private/Templates/User/PaymentForm.fluid.html**

```html
<f:form.select options="{user.availablePaymentOptions}"
               property="preferredPayment"
               prependOptionLabel="Ask me every time!"
               prependOptionValue="ask"
/>
```

You can achieve the same effect by combining  the
[options](https://docs.typo3.org/permalink/t3viewhelper:viewhelper-argument-typo3-cms-fluid-viewhelpers-form-selectviewhelper-options@13.4)
argument with one (or several)
[\<form.select.option> \<f:form.select.option>](https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-form-select-option@13.4):

**packages/my_extension/Resources/Private/Templates/User/PaymentForm.fluid.html**

```html
<f:form.select options="{user.availablePaymentOptions}"
               property="preferredPayment"
               optionsAfterContent="true"
               required="1"
>
   <f:form.select.option value="">Please Chose *</f:form.select.option>
   <f:form.select.option value="ask">Ask me every time!</f:form.select.option>
</f:form.select>
```

It is possible to put the additional options last and combine the two:

**packages/my_extension/Resources/Private/Templates/User/PaymentForm.fluid.html**

```html
<f:form.select options="{user.availablePaymentOptions}"
               property="preferredPayment"
               prependOptionLabel="Please Chose *"
               required="1"
>
   <f:form.select.option value="ask">Ask me every time!</f:form.select.option>
</f:form.select>
```

## Arguments of the Form.select ViewHelper

> **Allows arbitrary arguments**
>
> This ViewHelper allows you to pass arbitrary arguments not defined below
> directly to the HTML tag created. This includes custom `data-` arguments.

-   **additionalAttributes**

    -   *Type:* array

    Additional tag attributes. They will be added directly to the resulting HTML tag.

-   **aria**

    -   *Type:* array

    Additional aria-\* attributes. They will each be added with a "aria-" prefix.

-   **data**

    -   *Type:* array

    Additional data-\* attributes. They will each be added with a "data-" prefix.

-   **errorClass**

    -   *Type:* string
    -   *Default:* 'f3-form-error'

    CSS class to set if there are errors for this ViewHelper

-   **multiple**

    -   *Type:* boolean
    -   *Default:* false

    If set multiple options may be selected.

-   **name**

    -   *Type:* string

    Name of input tag

-   **optionLabelField**

    -   *Type:* string

    If specified, will call the appropriate getter on each object to determine the label.

-   **optionValueField**

    -   *Type:* string

    If specified, will call the appropriate getter on each object to determine the value.

-   **options**

    -   *Type:* array

    Associative array with internal IDs as key, and the values are displayed in the select box. Can be combined with or replaced by child f:form.select.\* nodes.

-   **optionsAfterContent**

    -   *Type:* boolean
    -   *Default:* false

    If true, places auto-generated option tags after those rendered in the tag content. If false, automatic options come first.

-   **prependOptionLabel**

    -   *Type:* string

    If specified, will provide an option at first position with the specified label.

-   **prependOptionValue**

    -   *Type:* string

    If specified, will provide an option at first position with the specified value.

-   **property**

    -   *Type:* string

    Name of Object Property. If used in conjunction with \<f:form object="...">, the "name" property will be ignored, while "value" can be used to specify a default field value instead of the object property value.

-   **required**

    -   *Type:* boolean
    -   *Default:* false

    If set no empty value is allowed.

-   **selectAllByDefault**

    -   *Type:* boolean
    -   *Default:* false

    If specified options are selected if none was set before.

-   **sortByOptionLabel**

    -   *Type:* boolean
    -   *Default:* false

    If true, List will be sorted by label.

-   **value**

    -   *Type:* mixed

    Value of input tag

## Arguments of the Form.select.option ViewHelper

> **Allows arbitrary arguments**
>
> This ViewHelper allows you to pass arbitrary arguments not defined below
> directly to the HTML tag created. This includes custom `data-` arguments.

-   **additionalAttributes**

    -   *Type:* array

    Additional tag attributes. They will be added directly to the resulting HTML tag.

-   **data**

    -   *Type:* array

    Additional data-\* attributes. They will each be added with a "data-" prefix.

-   **selected**

    -   *Type:* boolean

    If set, overrides automatic detection of selected state for this option.

-   **value**

    -   *Type:* mixed

    Value to be inserted in HTML tag - must be convertible to string!

## Arguments of the Form.select.optgroup ViewHelper

> **Allows arbitrary arguments**
>
> This ViewHelper allows you to pass arbitrary arguments not defined below
> directly to the HTML tag created. This includes custom `data-` arguments.

-   **additionalAttributes**

    -   *Type:* array

    Additional tag attributes. They will be added directly to the resulting HTML tag.

-   **data**

    -   *Type:* array

    Additional data-\* attributes. They will each be added with a "data-" prefix.

-   **disabled**

    -   *Type:* boolean
    -   *Default:* false

    If true, option group is rendered as disabled