Form.countrySelect ViewHelper <f:form.countrySelect>

ViewHelper which renders a <select> tag with all or specific countries as options.

Go to the source code of this ViewHelper: Form\CountrySelectViewHelper.php (GitHub).

A basic country selector bound to an action argument

For example a very simplified search form could look like this:

packages/my_extension/Resources/Private/Templates/User/SelectCountry.html 
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      data-namespace-typo3-fluid="true">
<f:form action="saveCountry">
    <f:form.countrySelect name="country" value="{defaultCountry}"/>
    <f:form.submit value="Submit"/>
</f:form>
</html>
Copied!

The Extbase controller action could for example look like this:

packages/my_extension/Classes/Controller/UserController.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
{
    /**
     * @param string $country ISO 2 country code ("BE", "FR", "US", ...)
     */
    public function createAction(string $country): ResponseInterface
    {
        return $this->redirect('show');
    }
}
Copied!

Prioritize countries

Define a list of countries which should be listed as first options in the form element by setting prioritizedCountries:

packages/my_extension/Resources/Private/Templates/User/SelectCountry.html 
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      data-namespace-typo3-fluid="true">
<f:form action="saveCountry">
    <f:form.countrySelect
        name="country"
        value="AT"
        prioritizedCountries="{0: 'DE', 1: 'AT', 2: 'CH'}"
    />
    <f:form.submit value="Submit"/>
</f:form>
</html>
Copied!

Additionally, Austria is pre-selected.

Display another language

A combination of optionLabelField and alternativeLanguage is possible. For instance, if you want to show the localized official names but not in your default language but in French. You can achieve this by using the following combination:

packages/my_extension/Resources/Private/Templates/User/SelectCountry.html 
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      data-namespace-typo3-fluid="true">
<f:form action="saveCountry">
    <f:form.countrySelect
        name="country"
        optionLabelField="localizedOfficialName"
        alternativeLanguage="fr"
        sortByOptionLabel="true"
    />
    <f:form.submit value="Submit"/>
</f:form>
</html>
Copied!

Bind the country selector to an Extbase model

You can also use the property attribute if you have bound an object to the form.

packages/my_extension/Resources/Private/Templates/User/SelectCountry.html 
<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      data-namespace-typo3-fluid="true">
<f:form action="saveCountry" object="{user}" name="user">
    <f:form.countrySelect property="country"/>
    <f:form.submit value="Submit"/>
</f:form>
</html>
Copied!
packages/my_extension/Classes/Domain/Model/User.php 
<?php

namespace Vendor\Extension\Domain\Model;

use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;

class User extends AbstractEntity
{
    // The country in ISO 2 code
    protected $country = '';

    // Getter and setter
}
Copied!

Arguments of f:form.countrySelect

additionalAttributes

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

alternativeLanguage

alternativeLanguage
Type
string
If specified, the country list will be shown in the given language.

aria

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

data

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

errorClass

errorClass
Type
string
Default
'f3-form-error'
CSS class to set if there are errors for this ViewHelper

excludeCountries

excludeCountries
Type
array
Default
array ( )
Array with country codes that should not be shown.

multiple

multiple
Type
boolean
Default
false
If set multiple options may be selected.

name

name
Type
string
Name of input tag

onlyCountries

onlyCountries
Type
array
Default
array ( )
If set, only the country codes in the list are rendered.

optionLabelField

optionLabelField
Type
string
Default
'localizedName'
If specified, will call the appropriate getter on each object to determine the label. Use "name", "localizedName", "officialName" or "localizedOfficialName"

prependOptionLabel

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

prependOptionValue

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

prioritizedCountries

prioritizedCountries
Type
array
Default
array ( )
A list of country codes which should be listed on top of the list.

property

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

required
Type
boolean
Default
false
If set no empty value is allowed.

sortByOptionLabel

sortByOptionLabel
Type
boolean
Default
false
If true, List will be sorted by label.

value

value
Type
mixed
Value of input tag