Form Fields

Overview of built-in form fields.

addText($name, $label=null)

Adds single line text field (class TextInput). Automatically trims left and right side whitespace. Beside preset validation rules, the following ones are available:

`Form::MIN_LENGTH`	minimal string length	`int $minLength`
`Form::MAX_LENGTH`	maximal string length	`int $maxLength`
`Form::LENGTH`	exact length	`[int $min, int $max]` or `int $length`
`Form::EMAIL`	is value a valid email address?
`Form::URL`	is value a valid URL?
`Form::PATTERN`	tests the entire value against a regular expression, kind of like it is inside ^ and a $	`string $pattern`
`Form::PATTERN_ICASE`	like `Form::PATTERN`, but case-insensitive	`string $pattern`
`Form::INTEGER`	is value integer?
`Form::NUMERIC`	alias of `Form::INTEGER`
`Form::FLOAT`	is value a floating point number?
`Form::MIN`	minimum of the integer value	`int\|float $minimum`
`Form::MAX`	maximum of the integer value	`int\|float $maximum`
`Form::RANGE`	is value in the range?	`[int $min, int $max]`

$form->addText('zip', 'Postcode:')
	->setRequired()
	->addRule(Form::PATTERN, 'Postcode must have exactly 5 numerals', '([0-9]\s*){5}');

The Form::INTEGER, NUMERIC a FLOAT rules automatically convert the value to integer (or float respectively). In addition, Form::URL automatically completes the URL, for example, nette.org will be completed to https://nette.org.

addPassword(string|int $name, $label=null): static

Adds password field (class TextInput). Automatically trims left and right side whitespace. Redrawing the form renders the input empty. Supports the same set of validation rules as addText.

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

addTextArea(string|int $name, $label=null): static

Adds a multiline text field (class TextArea). Supports the same set of validation rules as addText. Unlike oneline inputs, it does not trim the input's whitespace on either edge.

$form->addTextArea('note', 'Note:')
	->setRequired(false) // optional
	->addRule(Form::MAX_LENGTH, 'Your note is way too long', 10000);

addEmail(string|int $name, $label=null): static

Adds email address field with validity check (class TextInput). Supports the same set of validation rules as addText.

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

addInteger(string|int $name, $label=null): static

Adds input field for integer. Supports the same set of validation rules as addText.

$form->addInteger('level', 'Level:')
	->setDefaultValue(0)
	->addRule($form::RANGE, 'Level must be between %d and %d.', [0, 100]);

addUpload(string|int $name, $label=null): static

Adds file upload field (class UploadControl). Beside preset validation rules, the following ones are available:

`Form::MAX_FILE_SIZE`	verifies maximal file size	`int $bytes`
`Form::MIME_TYPE`	checks if MIME type is valid	`string $mimeType` or `$mimeTypes[]`. Can contain wildcards, such as `video/*`.
`Form::IMAGE`	checks if uploaded file is JPEG, PNG or GIF
`Form::PATTERN`	tests the file name against a regular expression	`string $pattern`
`Form::PATTERN_ICASE`	like `Form::PATTERN`, but case-insensitive	`string $pattern`

$form->addUpload('thumbnail', 'Thumbnail:')
	->setRequired(false) // optional
	->addRule(Form::IMAGE, 'Thumbnail must be JPEG, PNG or GIF')
	->addRule(Form::MAX_FILE_SIZE, 'Maximum file size is 64 kB.', 64 * 1024 /* size in Bytes */);

addMultiUpload(string|int $name, $label=null): static

Adds multiple file upload field. Validation rules are same as addUpload() and adds following:

`Form::MIN_LENGTH`	minimal count files	`int $minCount`
`Form::MAX_LENGTH`	maximal count files	`int $maxCount`
`Form::LENGTH`	exact count of uploaded files	`[int $minCount, int $maxCount]` or `int $count`

$form->addMultiUpload('files', 'Files');

addHidden(string|int $name, string $default=null): static

Adds hidden field (class HiddenField).

$form->addHidden('userid');

addCheckbox(string|int $name, $caption=null): static

Adds a checkbox (class Checkbox). The return value is either Boolean true or false, as checked or not checked.

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

addRadioList(string|int $name, $label=null, array $items=null): static

Adds radio buttons (class RadioList). Array of offered values is passed as the third argument.

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

// to list options within 1 line
$form->addRadioList('gender', 'Gender:', $sex)
	->getSeparatorPrototype()->setName(null);

addCheckboxList(string|int $name, $label=null, array $items=null): static

Adds list of checkboxes for selecting multiple elements. Array of values is passed as the third argument. The component checks if the submitted values are from the given range.

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

addSelect(string|int $name, $label=null, array $items=null): static

Adds select box (class SelectBox). Array of offered values is passed as third argument. Might as well be two-dimensional. The first item is often used as a call-to-action message, but worthless when actually selected – that's what method setPrompt() is for.

$countries = [
	'Europe' => [
		'CZ' => 'Czech republic',
		'SK' => 'Slovakia',
		'GB' => 'United Kingdom',
	],
	'CA' => 'Canada',
	'US' => 'USA',
	'?'  => 'other',
];
$form->addSelect('country', 'Country:', $countries)
	->setPrompt('Pick a country');

You can also add elements by using the setItems() method. If we want to get their values directly in place of key items, we can do this with the second argument:

$form->addSelect('country', 'Country:')
	->setItems($countries, false);

Individual items may be, in addition to strings, objects Nette\Utils\Html::('option'), which then can set additional HTML attributes. However, the selected and disabled attributes do not set this way, the form itself takes care of it. This also applies to addMultiSelect().

addMultiSelect(string|int $name, $label=null, array $items=null): static

Adds multichoice select box (class MultiSelectBox).

$form->addMultiSelect('options', 'Pick many:', $options);

addSubmit(string|int $name, $caption=null): static

Adds submit button (class SubmitButton).

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

It's okay to add more than one submit button.

$form->addSubmit('submit', 'Register');
$form->addSubmit('cancel', 'Cancel');

To find out which of them was clicked, use:

if ($form['submit']->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([]).

addButton(string|int $name, $caption): static

Adds button (class Button) without submit function. It is useful for binding other functionality to id, for example a JavaScript action.

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

addImage(string|int $name, $alt=null): static

Adds submit button in form of an image (class ImageButton).

$form->addImage('submit', '/path/to/image');

addContainer(string|int $name): static

Adds a sub-form (class Container), or a container, which can be treated the same way as a form. That means you can use methods like setDefaults() or getValues().

$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:');