Form Controls
*************

.[perex]
Overview of built-in form controls.


addText(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput .[method]
========================================================================================

Adds single line text field (class [TextInput |api:Nette\Forms\Controls\TextInput]). If the user does not fill in the field, it returns an empty string `''`, or use `setNullable()` to change it to return `null`.

```php
$form->addText('name', 'Name:')
	->setRequired()
	->setNullable();
```

It automatically validates UTF-8, trims left and right whitespaces, and removes line breaks that could be sent by an attacker.

The maximum length can be limited using `setMaxLength()`. The [addFilter()|validation#Modifying Input Values] allows you to change the user-entered value.

You can change the visual character of a text field to types like `search`, `tel`, or `url` using `setHtmlType()`, as seen in the [specification|https://developer.mozilla.org/en-US/docs/Learn/Forms/HTML5_input_types]. Remember that changing the type is only visual and does not perform validation functions. For the `url` type, it is appropriate to add a specific [URL rule|validation#Text inputs].

.[note]
For other input types such as `number`, `range`, `email`, `date`, `datetime-local`, `time`, and `color`, use specialized methods like [#addInteger], [#addFloat], [#addEmail] [#addDate], [#addTime], [#addDateTime], and [#addColor], which ensure server-side validation. The types `month` and `week` are not yet fully supported in all browsers.

The so-called empty-value can be set for the element, which is something like the default value, but if the user does not overwrite it, returns empty string or `null`.

```php
$form->addText('phone', 'Phone:')
	->setHtmlType('tel')
	->setEmptyValue('+420');
```


addTextArea(string|int $name, $label=null): TextArea .[method]
==============================================================

Adds a multiline text field (class [TextArea |api:Nette\Forms\Controls\TextArea]). If the user does not fill in the field, it returns an empty string `''`, or use `setNullable()` to change it to return `null`.

```php
$form->addTextArea('note', 'Note:')
	->addRule($form::MAX_LENGTH, 'Your note is way too long', 10000);
```

Automatically validates UTF-8 and normalizes line breaks to `\n`. Unlike a single-line input field, it does not trim the whitespace.

The maximum length can be limited using `setMaxLength()`. The [addFilter()|validation#Modifying Input Values] allows you to change the user-entered value. You can set the so-called empty-value using `setEmptyValue()`.


addInteger(string|int $name, $label=null): TextInput .[method]
==============================================================

Adds input field for integer (class [TextInput |api:Nette\Forms\Controls\TextInput]). Returns either an integer or `null` if the user does not enter anything.

```php
$form->addInteger('year', 'Year:')
	->addRule($form::RANGE, 'The year must be in the range %d to %d.', [1900, 2023]);
```

The element is rendered as `<input type="numeric">`. By using the `setHtmlType()` method, you can change the type to `range` for display as a slider, or to `text` if you prefer a standard text field without the special behavior of `numeric`.


addFloat(string|int $name, $label=null): TextInput .[method]{data-version:3.1.12}
=================================================================================

Adds a field for entering a decimal number ([TextInput |api:Nette\Forms\Controls\TextInput] class). Returns either float or `null`, if the user does not specify anything.

```php
$form->addFloat('level', 'Level:')
	->setDefaultValue(0)
	->addRule($form::RANGE, 'The level must be in the range %d to %d.', [0, 100]);
```

The element is rendered as `<input type="numeric">`. By using the `setHtmlType()` method, you can change the type to `range` for display as a slider, or to `text` if you prefer a standard text field without the special behavior of `numeric`.

Nette and the Chrome browser accept both a comma and a dot as decimal separators. To make this functionality available in Firefox, it is recommended to set the `lang` attribute either for the specific element or for the entire page, for example, `<html lang="cs">`.


addEmail(string|int $name, $label=null, int $maxLength=255): TextInput .[method]
================================================================================

Adds email address field with validity check (class [TextInput |api:Nette\Forms\Controls\TextInput]). If the user does not fill in the field, it returns an empty string `''`, or use `setNullable()` to change it to return `null`.

```php
$form->addEmail('email', 'Email:');
```

Verifies that the value is a valid email address. It does not verify that the domain actually exists, only the syntax is verified. Automatically validates UTF-8, trims left and right whitespaces.

The maximum length can be limited using `setMaxLength()`. The [addFilter()|validation#Modifying Input Values] allows you to change the user-entered value. You can set the so-called empty-value using `setEmptyValue()`.


addPassword(string|int $name, $label=null, $cols, ?int $maxLength=null): TextInput .[method]
============================================================================================

Adds password field (class [TextInput |api:Nette\Forms\Controls\TextInput]).

```php
$form->addPassword('password', 'Password:')
	->setRequired()
	->addRule($form::MIN_LENGTH, 'Password has to be at least %d characters long', 8)
	->addRule($form::PATTERN, 'Password must contain a number', '.*[0-9].*');
```

When you re-send the form, the input will be blank. It automatically validates UTF-8, trims left and right whitespaces, and removes line breaks that could be sent by an attacker.


addCheckbox(string|int $name, $caption=null): Checkbox .[method]
================================================================

Adds a checkbox (class [Checkbox |api:Nette\Forms\Controls\Checkbox]). The field returns either `true` or `false`, depending on whether it is checked.

```php
$form->addCheckbox('agree', 'I agree with terms')
	->setRequired('You must agree with our terms');
```


addCheckboxList(string|int $name, $label=null, ?array $items=null): CheckboxList .[method]
==========================================================================================

Adds list of checkboxes for selecting multiple items (class [CheckboxList |api:Nette\Forms\Controls\CheckboxList]). Returns the array of keys of the selected items. The `getSelectedItems()` method returns values instead of keys.

```php
$form->addCheckboxList('colors', 'Colors:', [
	'r' => 'red',
	'g' => 'green',
	'b' => 'blue',
]);
```

We pass the array of items as the third parameter, or by the `setItems()` method.

You can use `setDisabled(['r', 'g'])` to disable individual items.

The element automatically checks that there has been no forgery and that the selected items are actually one of the offered ones and have not been disabled. The `getRawValue()` method can be used to retrieve submitted items without this important check.

When default values are set, it also checks that they are one of the offered items, otherwise it throws an exception. This check can be turned off with `checkDefaultValue(false)`.

If you are submitting a form using the `GET` method, you can choose a more compact data transfer method that saves on the size of the query string. This is activated by setting the HTML attribute of the form:

```php
$form->setHtmlAttribute('data-nette-compact');
```


addRadioList(string|int $name, $label=null, ?array $items=null): RadioList .[method]
====================================================================================

Adds radio buttons (class [RadioList |api:Nette\Forms\Controls\RadioList]). Returns the key of the selected item, or `null` if the user did not select anything. The `getSelectedItem()` method returns a value instead of a key.

```php
$sex = [
	'm' => 'male',
	'f' => 'female',
];
$form->addRadioList('gender', 'Gender:', $sex);
```

We pass the array of items as the third parameter, or by the `setItems()` method.

You can use `setDisabled(['m'])` to disable individual items.

The element automatically checks that there has been no forgery and that the selected item is actually one of the offered ones and has not been disabled. The `getRawValue()` method can be used to retrieve the submitted item without this important check.

When default value is set, it also checks that it is one of the offered items, otherwise it throws an exception. This check can be turned off with `checkDefaultValue(false)`.


addSelect(string|int $name, $label=null, ?array $items=null, ?int $size=null): SelectBox .[method]
==================================================================================================

Adds select box (class [SelectBox |api:Nette\Forms\Controls\SelectBox]). Returns the key of the selected item, or `null` if the user did not select anything. The `getSelectedItem()` method returns a value instead of a key.

```php
$countries = [
	'CZ' => 'Czech republic',
	'SK' => 'Slovakia',
	'GB' => 'United Kingdom',
];

$form->addSelect('country', 'Country:', $countries)
	->setDefaultValue('SK');
```

We pass the array of items as the third parameter, or by the `setItems()` method. The array of items can also be two-dimensional:

```php
$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];
```

For select boxes, the first item often has a special meaning, it serves as a call-to-action. Use the `setPrompt()` method to add such an entry.

```php
$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');
```

You can use `setDisabled(['CZ', 'SK'])` to disable individual items.

The element automatically checks that there has been no forgery and that the selected item is actually one of the offered ones and has not been disabled. The `getRawValue()` method can be used to retrieve the submitted item without this important check.

When default value is set, it also checks that it is one of the offered items, otherwise it throws an exception. This check can be turned off with `checkDefaultValue(false)`.


addMultiSelect(string|int $name, $label=null, ?array $items=null, ?int $size=null): MultiSelectBox .[method]
============================================================================================================

Adds multichoice select box (class [MultiSelectBox |api:Nette\Forms\Controls\MultiSelectBox]). Returns the array of keys of the selected items. The `getSelectedItems()` method returns values instead of keys.

```php
$form->addMultiSelect('countries', 'Countries:', $countries);
```

We pass the array of items as the third parameter, or by the `setItems()` method. The array of items can also be two-dimensional.

You can use `setDisabled(['CZ', 'SK'])` to disable individual items.

The element automatically checks that there has been no forgery and that the selected items are actually one of the offered ones and have not been disabled. The `getRawValue()` method can be used to retrieve submitted items without this important check.

When default values are set, it also checks that they are one of the offered items, otherwise it throws an exception. This check can be turned off with `checkDefaultValue(false)`.


addUpload(string|int $name, $label=null): UploadControl .[method]
=================================================================

Adds file upload field (class [UploadControl |api:Nette\Forms\Controls\UploadControl]). Returns the [FileUpload |http:request#FileUpload] object, even if the user has not uploaded a file, which can be find out by the `FileUpload::hasFile()` method.

```php
$form->addUpload('avatar', 'Avatar:')
	->addRule($form::IMAGE, 'Avatar must be JPEG, PNG, GIF or WebP')
	->addRule($form::MAX_FILE_SIZE, 'Maximum size is 1 MB', 1024 * 1024);
```

If the file did not upload correctly, the form was not submitted successfully and an error is displayed. I.e. it is not necessary to check the `FileUpload::isOk()` method.

Do not trust the original file name returned by method `FileUpload::getName()`, a client could send a malicious filename with the intention to corrupt or hack your application.

Rules `MIME_TYPE` and `IMAGE` detect required type of file or image by its signature. The integrity of the entire file is not checked. You can find out if an image is not corrupted for example by trying to [load it|http:request#toImage].


addMultiUpload(string|int $name, $label=null): UploadControl .[method]
======================================================================

Adds multiple file upload field (class [UploadControl |api:Nette\Forms\Controls\UploadControl]). Returns an array of objects [FileUpload |http:request#FileUpload]. The `FileUpload::hasFile()` method will return `true` for each of them.

```php
$form->addMultiUpload('files', 'Files:')
	->addRule($form::MAX_LENGTH, 'A maximum of %d files can be uploaded', 10);
```

If one of the files fails to upload correctly, the form was not submitted successfully and an error is displayed. I.e. it is not necessary to check the `FileUpload::isOk()` method.

Do not trust the original file names returned by method `FileUpload::getName()`, a client could send a malicious filename with the intention to corrupt or hack your application.

Rules `MIME_TYPE` and `IMAGE` detect required type of file or image by its signature. The integrity of the entire file is not checked. You can find out if an image is not corrupted for example by trying to [load it|http:request#toImage].


addDate(string|int $name, $label=null): DateTimeControl .[method]{data-version:3.1.14}
======================================================================================

Adds a field that allows the user to easily input a date consisting of year, month, and day (class [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

For the default value, it accepts either objects implementing the `DateTimeInterface`, a string with time, or a number representing a UNIX timestamp. The same applies to the `Min`, `Max`, or `Range` rule arguments, which define the minimum and maximum allowed date.

```php
$form->addDate('date', 'Date:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
```

By default, it returns a `DateTimeImmutable` object. Using the `setFormat()` method, you can specify a [text format|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] or timestamp:

```php
$form->addDate('date', 'Date:')
	->setFormat('Y-m-d');
```


addTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===============================================================================================================

Adds a field that allows the user to easily input time consisting of hours, minutes, and optionally seconds (class [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

For the default value, it accepts either objects implementing the `DateTimeInterface`, a string with time, or a number representing a UNIX timestamp. Only the time information from these inputs is used; the date is ignored. The same applies to the `Min`, `Max`, or `Range` rule arguments, which define the minimum and maximum allowed time. If the minimum value set is higher than the maximum, a time range spanning midnight is created.

```php
$form->addTime('time', 'Time:', withSeconds: true)
	->addRule($form::Range, 'Time must be between %d and %d.', ['12:30', '13:30']);
```

By default, it returns a `DateTimeImmutable` object (with a fictitious date of January 1, year 0). Using the `setFormat()` method, you can specify a [text format|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters]:

```php
$form->addTime('time', 'Time:')
	->setFormat('H:i');
```


addDateTime(string|int $name, $label=null, bool $withSeconds=false): DateTimeControl .[method]{data-version:3.1.14}
===================================================================================================================

Adds a field that allows the user to easily input both date and time consisting of year, month, day, hours, minutes, and optionally seconds (class [DateTimeControl |api:Nette\Forms\Controls\DateTimeControl]).

For the default value, it accepts either objects implementing the `DateTimeInterface`, a string with time, or a number representing a UNIX timestamp. The same applies to the `Min`, `Max`, or `Range` rule arguments, which define the minimum and maximum allowed date.

```php
$form->addDateTime('datetime', 'Date and Time:')
	->setDefaultValue(new DateTime)
	->addRule($form::Min, 'The date must be at least a month old.', new DateTime('-1 month'));
```

By default, it returns a `DateTimeImmutable` object. Using the `setFormat()` method, you can specify a [text format|https://www.php.net/manual/en/datetime.format.php#refsect1-datetime.format-parameters] or timestamp:

```php
$form->addDateTime('datetime')
	->setFormat(DateTimeControl::FormatTimestamp);
```


addColor(string|int $name, $label=null): ColorPicker .[method]{data-version:3.1.14}
===================================================================================

Adds a color selection field (class [ColorPicker |api:Nette\Forms\Controls\ColorPicker]). The color is a string in the format `#rrggbb`. If the user doesn't make a selection, the default color returned is black `#000000`.

```php
$form->addColor('color', 'Color:')
	->setDefaultValue('#3C8ED7');
```


addHidden(string|int $name, ?string $default=null): HiddenField .[method]
=========================================================================

Adds hidden field (class [HiddenField |api:Nette\Forms\Controls\HiddenField]).

```php
$form->addHidden('userid');
```

Use `setNullable()` to change it to return `null` instead of an empty string. The [addFilter()|validation#Modifying Input Values] allows you to change the submitted value.

Although the element is hidden, it is **important to realize** that its value can still be modified or spoofed by an attacker. Always thoroughly verify and validate all received values on the server side to prevent security risks associated with data manipulation.


addSubmit(string|int $name, $caption=null): SubmitButton .[method]
==================================================================

Adds submit button (class [SubmitButton |api:Nette\Forms\Controls\SubmitButton]).

```php
$form->addSubmit('submit', 'Register');
```

It is possible to have more than one submit button in the form:

```php
$form->addSubmit('register', 'Register');
$form->addSubmit('cancel', 'Cancel');
```

To find out which of them was clicked, use:

```php
if ($form['register']->isSubmittedBy()) {
  // ...
}
```

If you don't want to validate the form when a submit button is pressed (such as *Cancel* or *Preview* buttons), you can turn it off with [setValidationScope()|validation#Disabling Validation].


addButton(string|int $name, $caption): Button .[method]
=======================================================

Adds button (class [Button |api:Nette\Forms\Controls\Button]) without submit function. It is useful for binding other functionality to id, for example a JavaScript action.

```php
$form->addButton('raise', 'Raise salary')
	->setHtmlAttribute('onclick', 'raiseSalary()');
```


addImageButton(string|int $name, ?string $src=null, ?string $alt=null): ImageButton .[method]
=============================================================================================

Adds submit button in form of an image (class [ImageButton |api:Nette\Forms\Controls\ImageButton]).

```php
$form->addImageButton('submit', '/path/to/image');
```

When using multiple submit buttons, you can find out which one was clicked with `$form['submit']->isSubmittedBy()`.

.[note]
The method was called `addImage()` in version 3.0.


addContainer(string|int $name): Container .[method]
===================================================

Adds a sub-form (class [Container|api:Nette\Forms\Container]), or a container, which can be treated the same way as a form. That means you can use methods like `setDefaults()` or `getValues()`.

```php
$sub1 = $form->addContainer('first');
$sub1->addText('name', 'Your name:');
$sub1->addEmail('email', 'Email:');

$sub2 = $form->addContainer('second');
$sub2->addText('name', 'Your name:');
$sub2->addEmail('email', 'Email:');
```

The sent data is then returned as a multidimensional structure:

```php
[
	'first' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
	'second' => [
		'name' => /* ... */,
		'email' => /* ... */,
	],
]
```


Overview of Settings
====================

For all elements we can call the following methods (see [API documentation|https://api.nette.org/forms/3.1/Nette/Forms/Controls.html] for a complete overview):

.[table-form-methods language-php]
| `setDefaultValue($value)` | sets the default value
| `getValue()` 				| get current value
| `setOmitted()` 			| [#omitted values]
| `setDisabled()` 			| [#disabling inputs]

Rendering:
.[table-form-methods language-php]
| `setCaption($caption)`	| change the caption of the item
| `setTranslator($translator)` | sets translator
| `setHtmlAttribute($name, $value)` | sets the [HTML attribute |rendering#HTML attributes] of the element
| `setHtmlId($id)` 			| sets the HTML attribute `id`
| `setHtmlType($type)` 		| sets HTML attribute `type`
| `setHtmlName($name)`		| sets HTML attribute `name`
| `setOption($key, $value)` | sets [rendering data|rendering#Options]

Validation:
.[table-form-methods language-php]
| `setRequired()` 			| [mandatory field |validation]
| `addRule()` 				| set [validation rule |validation#Rules]
| `addCondition()`, `addConditionOn()` | set [validation condition|validation#Conditions]
| `addError($message)`		| [passing error message|validation#processing-errors]

The following methods can be called for the `addText()`, `addPassword()`, `addTextArea()`, `addEmail()`, `addInteger()` items:

.[table-form-methods language-php]
| `setNullable()`			| sets whether getValue() returns `null` instead of empty string
| `setEmptyValue($value)` 	| sets the special value which is treated as empty string
| `setMaxLength($length)`	| sets the maximum number of allowed characters
| `addFilter($filter)`		| [modifying Input Values |validation#Modifying Input Values]


Omitted Values
==============

If you are not interested in the value entered by the user, we can use `setOmitted()` to omit it from the result provided by the `$form->getValues​()` method or passed to handlers. This is suitable for various passwords for verification, antispam fields, etc.

```php
$form->addPassword('passwordVerify', 'Password again:')
	->setRequired('Fill your password again to check for typo')
	->addRule($form::EQUAL, 'Password mismatch', $form['password'])
	->setOmitted();
```


Disabling Inputs
================

Inputs can be disabled using `setDisabled()`. A disabled input cannot be edited by the user.

```php
$form->addText('username', 'User name:')
	->setDisabled();
```

Disabled inputs are not sent to the server by the browser, so you won't find them in the data returned by the `$form->getValues()` function. However, if you set `setOmitted(false)`, Nette will include their default value in this data.

When `setDisabled()` is called, **the input's value is erased** for security reasons. If you are setting a default value, it is necessary to do so after its deactivation:

```php
$form->addText('username', 'User name:')
	->setDisabled()
	->setDefaultValue($userName);
```

An alternative to disabled inputs are fields with the HTML `readonly` attribute, which are sent to the server by the browser. Although the field is only readable, it is **important to realize** that its value can still be modified or spoofed by an attacker.


Custom Controls
===============

Besides wide range of built-in form controls you can add custom controls to the form as follows:

```php
$form->addComponent(new DateInput('Date:'), 'date');
// alternative syntax: $form['date'] = new DateInput('Date:');
```

There is a way to define new form methods for adding custom elements (eg `$form->addZip()`). These are the so-called extension methods. The downside is that code hints in editors won't work for them.

```php
use Nette\Forms\Container;

// adds method addZip(string $name, ?string $label = null)
Container::extensionMethod('addZip', function (Container $form, string $name, ?string $label = null) {
	return $form->addText($name, $label)
		->addRule($form::PATTERN, 'At least 5 numbers', '[0-9]{5}');
});

// usage
$form->addZip('zip', 'ZIP code:');
```


Low-Level Fields
================

To add an item to the form, you don't have to call `$form->addXyz()`. Form items can be introduced exclusively in templates instead. This is useful if you, for example, need to generate dynamic items:

```latte
{foreach $items as $item}
	<p><input type=checkbox name="sel[]" value={$item->id}> {$item->name}</p>
{/foreach}
```

After submission, you can retrieve the values:

```php
$data = $form->getHttpData($form::DATA_TEXT, 'sel[]');
$data = $form->getHttpData($form::DATA_TEXT | $form::DATA_KEYS, 'sel[]');
```

In the first parameter, you specify element type (`DATA_FILE` for `type=file`, `DATA_LINE` for one-line inputs like `text`, `password` or `email` and `DATA_TEXT` for the rest). The second parameter matches HTML attribute `name`. If you need to preserve keys, you can combine the first parameter with `DATA_KEYS`. This is useful for `select`, `radioList` or `checkboxList`.

The `getHttpData()` returns sanitized input. In this case, it will always be array of valid UTF-8 strings, no matter what the attacker sent by the form. It's an alternative to working with `$_POST` or `$_GET` directly if you want to receive safe data.