Improve this page
Version 3.0
◄ Forms Form Validation ►

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:');
◄ Forms Form Validation ►