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