---
title: "Elements"
version: "4.0"
permalink: "https://docs.typo3.org/permalink/ameos/ameos_form:elements@4.0"
source: "Elements/Index.rst"
rendered: "2026-11-13T14:41:18+00:00"
---

<a id="elements-general"></a>

# Elements {#elements}

<!-- TODO: no Markdown rendering for "only" -->

**Table of content:**

The configuration of the element can be set with a table when creating the element

```
$form->add('my-element', 'text', array('placeholder' => 'My placeholder', 'class' => 'my-css-class'));

```

Or after instanciation

```
$form->add('my-element', 'text');
$form->get('my-element')->with('placeholder', 'My placeholder');

```

## Button {#elements-button}

Classic html button.

![](../Images/button.png)

You can add a button like this

```
$form->add('my-button', 'button', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| label | label of the button |  | click me! |
| htmllabel | true to output the label(s) as HTML | false | true (trusted labels only, never records or user input) |

## Captcha {#elements-captcha}

![](../Images/captcha.png)

You can add a captcha like this

```
$form->add('my-captcha', 'captcha', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | Enter the code |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| errormessage | Message if the captcha is not valid | Captcha is not valid | Captcha is not valid |

## Checkbox {#elements-checkbox}

![](../Images/checkbox.png)

You can add a checkbox like this

```
$form->add('my-checkbox', 'checkbox', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| items | avalaible choice for checkbox |  | array('1' => 'Item 1', '2' => 'Item 2'); |
| htmllabel | true to output the label(s) as HTML | false | true (trusted labels only, never records or user input) |
| separator | html between the choices |  | \<br /> |
| clausetype | search clause type for each value | contains | contains (relation) or inList (comma separated list) |

The value is the list of the checked values (stored as a comma separated list).

## Checksingle {#elements-checksingle}

![](../Images/checksingle.png)

You can add a checksingle (yes/no choice) like this

```
$form->add('istrue', 'checksingle', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |

## Color {#elements-color}

![](../Images/color.png)

You can add a input color like this. Work only with html5 browser.

```
$form->add('my-color-field', 'color', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |

## Date {#elements-date}

![](../Images/date.png)

You can add a date like this.

```
$form->add('birthdate', 'date', $configuration);

```

The value is a `\DateTime` (or `null`). It accepts a `\DateTimeInterface`, a timestamp, a `Y-m-d` string
or an array `['year' => .., 'month' => .., 'day' => ..]`.

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| class | css class for the html tags |  | big |
| errorclass | css class when there is an error |  | error |
| widget | "choice" (3 select boxes) or "text" (date input) | choice | text |
| format-display | order of the select boxes (choice widget) | ymd | dmy, mdy, ymd |
| input | "timestamp" to get a timestamp as value |  | timestamp |

With the choice widget, an empty date displays the current date.

## Textdate {#elements-textdate}

A date rendered as html date input (same as the date element with `widget` = `text`). An empty value
is rendered empty.

```
$form->add('startdate', 'textdate', $configuration);

```

## Time {#elements-time}

You can add a time like this.

```
$form->add('meeting', 'time', $configuration);

```

The value is a `hh:mm` string (empty when no time is given).

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| widget | "choice" (hour and minute fields) or "text" | choice | text |
| minutestep | step of the proposed minutes (choice widget) | 1 | 15 |

## Dropdown {#elements-dropdown}

![](../Images/dropdown.png)

You can add a checkbox like this

```
$form->add('my-dropdown', 'dropdown', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| items | avalaible choice for checkbox |  | array('1' => 'Item 1', '2' => 'Item 2') or a repository result ($this->myrepo->findAll()) |

## Email {#elements-email}

![](../Images/email.png)

You can add a input email like this. Work only with html5 browser.

```
$form->add('my-email', 'email', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |

## hidden {#elements-hidden}

You can add a input hidden like this.

```
$form->add('my-hidden-field', 'hidden', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |

## Number {#elements-number}

![](../Images/number.png)

You can add a input hidden like this. Work only with html5 browser.

```
$form->add('my-number-field', 'number', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| min | minimum number |  | 10 |
| max | maximum number |  | 100 |
| step | increment step between each number | 1 | 10 |

## Password {#elements-password}

![](../Images/password.png)

You can add a input password like this.

```
$form->add('my-password', 'password', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| encrypt | if true, password is encrypt | false | true |
| fill_value | if true, add current value in html | false | true |

## Radio button {#elements-radio}

![](../Images/radio.png)

You can add a checkbox like this

```
$form->add('my-radiobutton', 'radio', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| items | avalaible choice for checkbox |  | array('1' => 'Item 1', '2' => 'Item 2'); |
| htmllabel | true to output the label(s) as HTML | false | true (trusted labels only, never records or user input) |

## Range {#elements-range}

![](../Images/range.png)

You can add a input hidden like this. Work only with html5 browser.

```
$form->add('my-range-field', 'range', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| min | minimum number |  | 10 |
| max | maximum number |  | 100 |
| step | increment step between each number | 1 | 10 |

## Radio button {#elements-rating}

![](../Images/rating.png)

You can add a rating element like this

```
$form->add('my-rating', 'rating', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| min | score min | 1 | 10 |
| max | score max | 5 | 50 |
| step | step between score | 1 | 2 |
| label | label of item | ★ |  |

## ReCaptcha {#elements-recaptcha}

![](../Images/recaptcha.png)

You can add a recaptcha like this

```
$form->add('my-recaptcha', 'recaptcha', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| publicKey | Your api public key (required) |  |  |
| privateKey | Your api private key (required) |  |  |
| onload | The name of your callback function to be executed once all the dependencies have loaded. (optional) |  |  |
| render | Whether to render the widget explicitly. Defaults to onload, which will render the widget in the first g-recaptcha tag it finds. (optional) |  |  |
| language | Forces the widget to render in a specific language. Auto-detects the user's language if unspecified. (optional) Language codes: [https://developers.google.com/recaptcha/docs/language](https://developers.google.com/recaptcha/docs/language)    en-GB |  |  |
| theme | The color theme of the widget (optional) | light | dark or light |
| type | The type of CAPTCHA to serve (optional) | image | audio or image |
| size | The size of the widget (optional) | normal | compact or normal |
| tabindex | The tabindex of the widget and challenge (optional) |  |  |
| callback | The name of your callback function to be executed when the user submits a successful CAPTCHA response. The user's response, g-recaptcha-response, will be the input for your callback function. (optional) |  |  |
| expired-callback | The name of your callback function to be executed when the recaptcha response expires and the user needs to solve a new CAPTCHA. (optional) |  |  |
| errormessage | Message if the captcha is not valid | Captcha is not valid | Captcha is not valid |

## Submit {#elements-submit}

![](../Images/submit.png)

You can add a submit button like this

```
$form->add('my-button', 'submit', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| label | label of the button |  | click me! |

## Tel {#elements-tel}

An input telephone field

![](../Images/tel.png)

You can add a input tel like this

```
$form->add('my-tel', 'tel', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | Your telephone |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| datalist | datalist for autocomplete |  | array('key-1' => 'value 1', 'key-2' => 'value 2') |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| pattern | regex for field control |  | ^((+d{1,3}(-\| )?(?d)?(-\| )?d{1,5})\|((?d{2,6})?))(-\| )?(d{3,4})(-\| )?(d{4})(( x\| ext)d{1,5}){0,1}$ |

## Text {#elements-text}

An input text field

![](../Images/text.png)

You can add a input text like this

```
$form->add('my-text', 'text', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| datalist | datalist for autocomplete |  | array('key-1' => 'value 1', 'key-2' => 'value 2') |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |

## Textarea {#elements-textarea}

![](../Images/textarea.png)

You can add a textarea like this

```
$form->add('my-textarea', 'textarea', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |

## Upload {#elements-upload}

![](../Images/upload.png)

You can add an upload field like this

```
$form->add('my-file', 'upload', $configuration);

```

Files are first stored outside the public path, in `var/transient/ameos_form/upload/`, with a random prefix
(pending files are displayed by name, without link), and moved to `directory` with their sanitized original name
when the form is valid. Files rejected by a constraint are deleted, abandoned temporary files after 24 hours.

> [!WARNING]
> `directory` is usually public (`fileadmin/...`): always restrict the allowed files with the
> `fileextension` (and `filemime`) constraints, e.g. to avoid uploaded HTML or SVG files executing
> scripts on your domain. Only PHP-like files are refused by default (`fileDenyPattern`).

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | my firstname |
| style | css style for the html tag |  | width: 150px; |
| title | html tag title |  | my field title |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |
| directory | target upload directory (required) |  | fileadmin/user_upload/my_ext/ |
| multiple | if true, several files are allowed | false | true or false |
| maxSize | maximum size of a file | 5M | 500K, 2M, 1G or a size in bytes |
| filename | target upload file name |  | my-file.pdf |
| canoverwrite | if true, overwrite existing file |  | true or false |
| show_link | if true, display an link to the file |  | true or false |

## Url {#elements-url}

An input url field

![](../Images/url.png)

You can add a input url like this

```
$form->add('my-url', 'url', $configuration);

```

Available configuration

| Property | Description | Default value | Example |
| --- | --- | --- | --- |
| placeholder | place holder for the html tag |  | Your website |
| style | css style for the html tag |  | width: 150px; |
| disabled | true if the html field is disabled | false | true or false |
| title | html tag title |  | my field title |
| datalist | datalist for autocomplete |  | array('key-1' => 'value 1', 'key-2' => 'value 2') |
| custom | custom html attribute |  | customattr="customvalue" |
| class | css class for the html tag |  | big |
| errorclass | css class when there is an error |  | error |

## Custom {#custom}

You can also create your own form element.

```
$form->add('my-custom', 'Vendor\\Extension\\FormElements\\MyElement', $configuration)

```

Your php class must implement :

```
Ameos\AmeosForm\Elements\ElementInterface
```