Nette Forms

https://github.com/nette/forms
Admin
Nette Forms is a PHP library that greatly facilitates creating and processing secure web forms,...
Tokens:144,252
Snippets:1,018
Trust Score:9.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Client-side Support with npm

Source: https://github.com/nette/forms/blob/master/readme.md

Install the nette-forms client-side JavaScript package using npm or yarn.

```bash
npm install nette-forms
```

--------------------------------

### GET-form manual rendering example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rendering.md

Manual rendering example from examples/manual-rendering.php. Shows how to render the form begin tag, insert custom markup with control labels and controls, then render the end tag.

```php
$form->render('begin');
// ... manual markup, e.g. <?php echo $form['name']->getLabel() ?> <?php echo $form['name']->control ?>
$form->render('end');
```

--------------------------------

### Install Nette Forms via Composer

Source: https://github.com/nette/forms/blob/master/readme.md

Install the nette/forms package using Composer. Requires PHP 8.3 and supports up to PHP 8.5.

```bash
composer require nette/forms
```

--------------------------------

### webalize usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Shows how to import nette from 'nette-forms' and call webalize. The example converts 'Příliš žluťoučký kůň' to 'prilis-zlutoucky-kun'.

```typescript
import nette from 'nette-forms';
nette.webalize('Příliš žluťoučký kůň'); // 'prilis-zlutoucky-kun'
```

--------------------------------

### setDefaults usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/container.md

Shows how to set default values for a container, including nested containers for address fields.

```php
public function setDefaults([
	'name' => 'John Doe',
	'address' => ['street' => 'Main St'],   // nested container
]);
```

--------------------------------

### TextArea usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/text-controls.md

Example of creating a textarea with a required rule.

```php
$form->addTextArea('bio', 'About you:', cols: 40, rows: 5)
	->setRequired('Tell us something');
```

--------------------------------

### Blueprint::latte() and dataClass() usage examples

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/blueprint.md

Shows how to call the static methods. The first prints the blueprint and exits; the second prints and continues the request.

```php
Nette\Forms\Blueprint::latte($form);            // print blueprint & exit
Nette\Forms\Blueprint::dataClass($form, exit: false); // print and continue the request
```

--------------------------------

### Client-side configuration example for nette-forms 4.0.0

Source: https://github.com/nette/forms/blob/master/_autodocs/configuration.md

Shows how to disable automatic initialization, load the UMD build, manually call `Nette.initOnLoad()`, and register a custom validator `check_zip` that validates a 5-digit ZIP code.

```html
<script>
	window.Nette = {noInit: true};      // take over initialization manually
</script>
<script src="nette-forms.umd.js"></script>
<script>
	Nette.initOnLoad();
	Nette.validators.check_zip = (elem, args, val) => /^\d{5}$/.test(val);
</script>
```

--------------------------------

### Create a Simple Registration Form

Source: https://github.com/nette/forms/blob/master/readme.md

Create a basic Nette form with text, password, and submit fields, then render it by echoing the form object.

```php
use Nette\Forms\Form;

$form = new Form;

$form->addText('name', 'Name:');
$form->addPassword('password', 'Password:');
$form->addSubmit('send', 'Register');

echo $form; // renders the form
```

--------------------------------

### ESM usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Shows how to import FormValidator from 'nette-forms' and create an instance, then call initOnLoad().

```ts
import { FormValidator } from 'nette-forms';
const validator = new FormValidator();
validator.initOnLoad();
```

--------------------------------

### Form rendering usage examples

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Shows three ways to render a form: full markup, partial 'begin' mode, and echo equivalent. The 'begin' mode is partial and depends on DefaultFormRenderer modes.

```php
$form->render();            // full markup (begin/errors/body/end)
$form->render('begin');     // partial — see DefaultFormRenderer modes
echo $form;                 // equivalent to render()
```

--------------------------------

### Using DateTimeControl factories

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/other-controls.md

Example of using Container factories addDate, addTime, and addDateTime to create DateTimeControl instances with rules and format settings.

```php
$form->addDate('birth', 'Date of birth')
	->addRule(Form::Range, 'Not before %s', [new DateTime('1900-01-01'), null]);
$form->addTime('alarm', 'Wake up', withSeconds: false);
$form->addDateTime('deadline', 'Deadline', withSeconds: true)
	->setFormat(DateTimeControl::FormatTimestamp);   // getValue() returns int
```

--------------------------------

### TextInput usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/text-controls.md

Example of creating text inputs with validation rules. The first adds required, min length, and pattern rules. The second sets type to number and adds a range rule that renders min and max attributes.

```php
$form->addText('nick', 'Nick:')
	->setRequired('Enter a nick')
	->addRule(Form::MinLength, 'At least %d characters', 3)
	->addRule(Form::Pattern, 'No spaces please', '\\S+');
$form->addText('qty')->setHtmlType('number')
	->addRule(Form::Range, '1–5', [1, 5]);   // renders min="1" max="5"
```

--------------------------------

### getValues usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/container.md

Shows how to retrieve form values in different formats: ArrayHash, plain array, typed DTO, and direct access to a single field.

```php
if ($form->isSuccess()) {
	$data = $form->getValues();                       // ArrayHash
	$array = $form->getValues(Container::Array);      // plain array
	/** @var UserData $dto */
	$dto = $form->getValues(UserData::class);         // typed DTO with public props
	$email = $form->getValues()['email'];
}
```

--------------------------------

### Essential Commands for Testing and Building

Source: https://github.com/nette/forms/blob/master/AGENTS.md

Commands for running PHP tests, static analysis, and JavaScript build/test/lint/typecheck tasks. PHP tests use Nette Tester; JS uses npm with Vitest and ESLint.

```bash
vendor/bin/tester tests -s -C        # or: composer tester
```

```bash
vendor/bin/tester tests/Forms/ -s -C
```

```bash
composer phpstan                     # PHPStan level 8
```

```bash
npm install
```

```bash
npm run build       # UMD + minified + .d.ts into src/assets/; runs JS tests after
```

```bash
npm run test        # Vitest (jsdom); test:watch / test:ui also available
```

```bash
npm run lint:fix    # ESLint with @nette/eslint-plugin
```

```bash
npm run typecheck
```

--------------------------------

### Blueprint::generateDataClass() usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/blueprint.md

Creates a Blueprint instance and generates a data class with property promotion and base name 'Signup'. The output shows a constructor-promoted class.

```php
$blueprint = new Blueprint;
echo $blueprint->generateDataClass($form, propertyPromotion: true, baseName: 'Signup');
// class SignupFormData
// {
//     public function __construct(
//         public string $name, …
//     ) {}
// }
```

--------------------------------

### RadioList usage example with getControlPart and getLabelPart

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/choice-controls.md

Shows how to create a RadioList and render a single item's input and label. The output includes generated ids like frm-gender-m when $generateId is true.

```php
$radio = $form->addRadioList('gender', null, ['m' => 'male', 'f' => 'female']);
echo $radio->getControlPart('m');   // <input type="radio" name="gender" value="m" id="frm-gender-m">
echo $radio->getLabelPart('m');     // <label for="frm-gender-m">male</label>
```

--------------------------------

### Example of filter and toggle usage

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rules.md

Shows adding a trim filter to a price field and toggling a checkbox based on a condition.

```php
$form->addText('price')->addFilter(fn($value) => trim($value));
$form->addCheckbox('news', 'Newsletter')
	->addCondition(Form::Filled)->toggle('newsBox');
```

--------------------------------

### createSelectBox() usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/helpers.md

Creates a select box with Czechia and Slovakia options, disabling Slovakia and selecting Czechia. The output shows the generated HTML with the selected and disabled attributes.

```php
echo Helpers::createSelectBox(['cz' => 'Czechia', 'sk' => 'Slovakia'], ['disabled:' => ['sk' => true]], 'cz');
// <select><option value="cz" selected>Czechia</option><option value="sk" disabled>Slovakia</option></select>
```

--------------------------------

### Generated statements for MinLength and SelectBox::Valid keys

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/forms-di.md

Shows the exact PHP statements generated for the example keys. The first uses the Form::MinLength constant, the second uses the bare constant expression.

```php
// for key 'MinLength':
Nette\Forms\Validator::$messages[Nette\Forms\Form::MinLength] = 'Please enter at least %d characters.';

// for key 'Nette\Forms\Controls\SelectBox::Valid' (bare constant expression):
Nette\Forms\Validator::$messages[Nette\Forms\Controls\SelectBox::Valid] = 'Pick something!';
```

--------------------------------

### renderBegin()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rendering.md

Resets the 'rendered' option on all controls and the pair counter, then emits the form prototype start tag, with GET-form query handling.

```APIDOC
## [PHP] renderBegin()

### Description
Resets the 'rendered' option on all controls and the pair counter, then emits the form prototype start tag, with GET-form query handling.

### Method
PHP method

### Endpoint
`public function renderBegin(): string`

### Response
#### Success Response
- **string** - The rendered HTML string.
```

--------------------------------

### Method and data-type constants

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Constants for HTTP methods (Get, Post), data types (DataText, DataLine, DataFile, DataKeys), and tracker ID.

```php
public const Get = 'get', Post = 'post';
public const DataText = 1, DataLine = 2, DataFile = 3, DataKeys = 8;
public const TrackerId = '_form_';
```

--------------------------------

### SelectBox usage with optgroups, prompt, and option attribute

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/choice-controls.md

Example of adding a select with nested optgroups, a prompt, and a per-option attribute. The '?' key creates a boolean attribute on the option, and setOptionAttribute('data-alpha', true) adds the attribute to all options.

```php
$form->addSelect('country', 'Country', [
	'World' => ['bu' => 'Buranda', 'qu' => 'Qumran'],
	'?' => 'other',
])
	->setPrompt('Select your country')
	->setOptionAttribute('data-alpha', true);
```

--------------------------------

### Add error and display form errors

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Example of adding a form-level error when the form is invalid and displaying all errors with HTML escaping.

```php
if (!$form->isValid()) {
	$form->addError('Please fix the highlighted fields.');
	echo implode('<br>', array_map('htmlspecialchars', $form->getErrors()));
}
```

--------------------------------

### ColorPicker usage example with setValue and exception handling

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/other-controls.md

Shows how to add a color picker with addColor(), set a valid hex value, and handle an invalid value that throws Nette\InvalidArgumentException with message 'Color must have #rrggbb format.'

```php
$form->addColor('accent', 'Accent color')
	->setValue('#336699');   // getValue() === '#336699'
try {
	$form['accent']->setValue('red');
} catch (Nette\InvalidArgumentException $e) {
	// 'Color must have #rrggbb format.'
}
```

--------------------------------

### Custom JsonRenderer example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/interfaces.md

Shows a custom FormRenderer implementation that outputs form data as JSON. Includes usage with a form, setting the renderer, and echoing the form to produce JSON output.

```php
use Nette\Forms\Form;
use Nette\Forms\FormRenderer;

final class JsonRenderer implements FormRenderer
{
	public function render(Form $form): string
	{
		$data = [];
		foreach ($form->getControls() as $name => $control) {
			$data[$name] = $control->getValue();
		}
		return json_encode(['errors' => $form->getErrors(), 'values' => $data]);
	}
}

$form = new Form;
$form->addText('name')->setRequired('Name required');
$form->setRenderer(new JsonRenderer);
echo $form; // {"errors":[...],"values":[...]}
```

--------------------------------

### Exporting rules to JSON

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/helpers.md

Example of serializing a control's rules to JSON for the data-nette-rules attribute. The output shows an array of rule objects with 'op' and 'msg' keys.

```php
$json = json_encode(Helpers::exportRules($control->getRules()));
// [{"op":":filled","msg":"This field is required."}, …]
```

--------------------------------

### toggleControl(elem, rules, success, firsttime, value, emptyOptional)

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Recursively evaluates toggles for a control. On the first pass, installs change listeners on participating controls (deduplicated by a WeakMap).

```APIDOC
## [METHOD] toggleControl(elem, rules, success, firsttime, value, emptyOptional)

### Description
Recursive toggle evaluation; on first pass installs `change` listeners on participating controls (deduped by a `WeakMap`).

### Method
`toggleControl`

### Endpoint
`toggleControl(elem, rules?, success: boolean | null = null, firsttime: boolean = false, value?, emptyOptional?): boolean`

### Parameters
- **elem** (FormElement) - Required - The form element.
- **rules** (Rule[]) - Optional - The rules to evaluate.
- **success** (boolean | null) - Optional - Initial success state.
- **firsttime** (boolean) - Optional - Whether this is the first evaluation.
- **value** - Optional - The value reference.
- **emptyOptional** - Optional - Whether the field is optional when empty.

### Response
Returns `true` if the control is visible, `false` otherwise.

### Example
```ts
const visible = v.toggleControl(elem);
```
```

--------------------------------

### Neon configuration for FormsExtension

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/forms-di.md

Example NEON configuration registering the FormsExtension service and setting custom validation messages. Keys can be short names like MinLength or full constant expressions like Nette\Forms\Controls\SelectBox::Valid.

```neon
services:
	- Nette\Bridges\FormsDI\FormsExtension

forms:
	messages:
		MinLength: 'Please enter at least %d characters.'
		Nette\Forms\Controls\SelectBox::Valid: 'Pick something!'
```

--------------------------------

### FormValidator usage: initForm and validateForm

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Shows how to enable client-side validation on a form and manually trigger validation. `initForm` wires the form (sets `noValidate`, installs submit/reset handlers), and `validateForm` returns `false` and shows errors in a modal when validation fails.

```ts
const v = new FormValidator();
const form = document.querySelector('form#signup')!;
v.initForm(form);                       // enable client validation
const ok = v.validateForm(form);        // manual trigger; false → errors shown in modal
```

--------------------------------

### HiddenField usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/text-controls.md

Example of creating hidden fields. The first is a regular hidden field that round-trips submitted values. The second is a typical persistent use for CSRF protection.

```php
$form->addHidden('userid');                 // submitted value round-trips
$form->addHidden('csrf-protection-token');  // typical persistent use
```

--------------------------------

### Custom control element hook example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rendering.md

Shows how to extend DefaultFormRenderer by overriding the protected renderControlElement method to add custom CSS classes to control elements. The example adds 'form-control' class for Bootstrap styling.

```php
final class MyRenderer extends DefaultFormRenderer
{
	protected function renderControlElement(Nette\Forms\Control $control): Html|string
	{
		return $control->getControl()->addClass('form-control'); // Bootstrap style
	}
}
$form->setRenderer(new MyRenderer);
```

--------------------------------

### getValue()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rendering.md

Protected method to get a value from the wrappers configuration.

```APIDOC
## [PHP] getValue()

### Description
Protected method to get a value from the wrappers configuration.

### Method
PHP method

### Endpoint
`protected function getValue(string $name): mixed`

### Parameters
#### Path Parameters
- **$name** (string) - Required - The value name.

### Response
#### Success Response
- **mixed** - The value.
```

--------------------------------

### getOptions()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/control-group.md

Returns all rendering options as an array.

```APIDOC
## getOptions()

### Description
Returns all rendering options as an array.

### Method
`public function getOptions(): array`

### Parameters
None.

### Return Value
Returns an associative array of all options.
```

--------------------------------

### Nette\Forms\SubmitterControl

Source: https://github.com/nette/forms/blob/master/_autodocs/types.md

Interface for submitter controls (e.g., submit buttons). Extends Control and provides a method to get the validation scope.

```APIDOC
## Interface: Nette\Forms\SubmitterControl

### Description
Interface for submitter controls (e.g., submit buttons). Extends Control and provides a method to get the validation scope.

### Methods

#### getValidationScope(): ?array
- **Returns**: ?list<Control|Container> - The validation scope, or null if not set.

### Usage
Returned by: `Form::isSubmitted()`; implemented by `Controls\SubmitButton`, `Controls\ImageButton`. Consumed by `Form::getValues()` (scope narrowing), `Form::fireEvents()`.
```

--------------------------------

### BaseControl options and extension methods

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/base-control.md

Methods for setting/getting options and registering extension methods. Options are user-defined keys consumed by renderers. extensionMethod() registers per-class callables; __call walks the class hierarchy before falling back to ObjectHelpers::strictCall().

```php
public function setOption(string $key, mixed $value): static
public function getOption(string $key): mixed
public function getOptions(): array
public function __call(string $name, array $args): mixed
public static function extensionMethod(string $name, callable $callback): void
```

--------------------------------

### Nette\Forms\Control

Source: https://github.com/nette/forms/blob/master/_autodocs/types.md

Interface for form controls. Defines methods for setting and getting values, validation, error retrieval, and omission status.

```APIDOC
## Interface: Nette\Forms\Control

### Description
Interface for form controls. Defines methods for setting and getting values, validation, error retrieval, and omission status.

### Methods

#### setValue(mixed $value): static
- **Parameters**: `$value` (mixed) - The value to set.
- **Returns**: static - The instance for chaining.

#### getValue(): mixed
- **Returns**: mixed - The current value.

#### validate(): void
- **Description**: Performs validation.

#### getErrors(): array
- **Returns**: list<string|\Stringable> - List of error messages.

#### isOmitted(): bool
- **Returns**: bool - Whether the control is omitted.

### Usage
Accepted by: `Container::addComponent()`, `ControlGroup::add()`, `Form` validation scope, `Validator::validateXxx()` (most), `Rules` construction, `Nette\Bridges\FormsLatte\Runtime::get($item, Control::class)`.
```

--------------------------------

### Include Client-side Validation Script

Source: https://github.com/nette/forms/blob/master/readme.md

Link the netteForms.js script to enable client-side validation. The file is located at /client-side/forms in the distribution package.

```html
<script src="netteForms.js"></script>
```

--------------------------------

### Using getError() after form validation

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/base-control.md

Example of retrieving the first error message from a form control after validation fails.

```php
if (!$form->isValid()) {
	echo $form['email']->getError();   // "Please enter a valid email address."
}
```

--------------------------------

### initOnLoad()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Automatically initializes all forms on the page when the DOM is ready. This is auto-invoked by the UMD build.

```APIDOC
## [METHOD] initOnLoad()

### Description
Runs `initForm` for every `document.forms` on DOM ready (auto-invoked by the UMD build).

### Method
`initOnLoad`

### Endpoint
`initOnLoad(): void`

### Parameters
None

### Response
No return value.

### Example
```ts
v.initOnLoad();
```
```

--------------------------------

### BaseControl::getOptions()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/base-control.md

Returns all user-defined options as an associative array.

```APIDOC
## [METHOD] getOptions

### Description
Returns all user-defined options as an associative array.

### Method
getOptions

### Signature
```php
public function getOptions(): array
```

### Return Value
array - Associative array of options.
```

--------------------------------

### Example of conditional rules

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rules.md

Demonstrates a condition on a text field: if filled, require min length; else require blank.

```php
$form->addText('sendBox')->addCondition(Form::Filled)
		->addRule(Form::MinLength, 'Too short', 3)
	->elseCondition()
		->addRule(Form::Blank, 'Must be blank')
	->endCondition();
```

--------------------------------

### Example usage of addRule

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rules.md

Shows adding an email validation rule and a custom callback rule that checks if the value is even.

```php
$input->addRule(Form::Email, 'Invalid email');
$input->addRule(fn(Control $control) => $control->getValue() % 2 === 0, 'Must be even');
```

--------------------------------

### Blueprint::latte() static method signature

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/blueprint.md

Generates a blueprint of a form Latte template. Prints a self-contained HTML page with Prism syntax highlighting and exits when $exit is true.

```php
/**
 * Generates blueprint of form Latte template.
 */
public static function latte(Form $form, bool $exit = true): void
```

--------------------------------

### Style Required Field Labels

Source: https://github.com/nette/forms/blob/master/readme.md

Nette adds a 'required' class to mandatory elements; this CSS turns the label of required inputs maroon.

```css
<style>
.required label { color: maroon }
</style>
```

--------------------------------

### render(mixed ...$args): void

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Renders the form. Fires render events and then echoes the renderer's output. Supports partial rendering modes like 'begin'.

```APIDOC
## render(mixed ...$args): void

### Description
Renders the form. Fires render events and then echoes the renderer's output. Supports partial rendering modes like 'begin'.

### Method
PHP method

### Signature
`public function render(mixed ...$args): void`

### Parameters
- **$args** (mixed) - Optional - Arguments passed to the renderer, e.g., 'begin' for partial rendering.

### Return Value
void

### Usage Examples
```php
$form->render();            // full markup (begin/errors/body/end)
$form->render('begin');     // partial — see DefaultFormRenderer modes
```
```

--------------------------------

### __toString(): string

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Magic method that returns the rendered form markup when the form is echoed.

```APIDOC
## __toString(): string

### Description
Magic method that returns the rendered form markup when the form is echoed.

### Method
PHP method

### Signature
`public function __toString(): string`

### Return Value
string - The rendered form markup.

### Usage Examples
```php
echo $form;                 // equivalent to render()
```
```

--------------------------------

### Creating unnamed and named Form instances

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Shows two ways to instantiate a Form. An unnamed form relies on method and data for submission detection, while a named form requires the hidden tracker '_form_' to match in POST/GET data.

```php
$form = new Form;   // unnamed — submission detection rests on method + data only
$form = new Form('signup');  // named — hidden tracker "_form_" must match in POST/GET data
```

--------------------------------

### compactCheckboxes(form, formData)

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Joins checkbox values with the same name ending in `[]` into a single comma-separated field in the FormData. Used for GET forms with `data-nette-compact`.

```APIDOC
## [METHOD] compactCheckboxes(form, formData)

### Description
Joins `name[]` checkbox values into one comma-separated field (used for GET forms with `data-nette-compact`).

### Method
`compactCheckboxes`

### Endpoint
`compactCheckboxes(form: HTMLFormElement, formData: FormData): void`

### Parameters
- **form** (HTMLFormElement) - Required - The form element.
- **formData** (FormData) - Required - The FormData object to modify.

### Response
No return value.

### Example
```ts
v.compactCheckboxes(form, formData);
```
```

--------------------------------

### Form rendering method signatures

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Declares rendering-related methods. getRenderer() lazily creates Rendering\DefaultFormRenderer. render() fires render events then echoes the renderer output; __toString() is the echo $form; path. getToggles() aggregates Rules::getToggleStates() over the control tree.

```php
public function setRenderer(?FormRenderer $renderer): static
public function getRenderer(): FormRenderer          // lazily creates Rendering\DefaultFormRenderer
protected function beforeRender()
public function fireRenderEvents(): void
public function render(mixed ...$args): void
public function __toString(): string
public function getToggles(): array                  // array<string, bool> for all toggle targets
```

--------------------------------

### Nette\Forms\SubmitterControl

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/interfaces.md

Interface for submittable controls (e.g., submit buttons). Extends Control and adds a method to get the validation scope.

```APIDOC
## Interface: `Nette\Forms\SubmitterControl`

### Description
Interface for submittable controls (e.g., submit buttons). Extends Control and adds a method to get the validation scope.

### Methods

#### `getValidationScope(): ?array`
- Returns the validation scope. Clicking the button validates only the controls within the scope, or null for all.
- Returns `?list<Control|Container>`.

### Source
`src/Forms/SubmitterControl.php` (line 14).
```

--------------------------------

### Add Required Validation to a Field

Source: https://github.com/nette/forms/blob/master/readme.md

Use setRequired() to make a field mandatory, with an optional custom error message shown when the field is left empty.

```php
$form->addText('name', 'Name:')
	->setRequired('Please fill your name.');
```

--------------------------------

### Static initialize method signature

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Initializes the shared Nette\Http\RequestFactory-built request for standalone (non-DI) usage. false keeps cached default, true forces re-creation from globals, a concrete IRequest replaces it. Only relevant outside Nette DI.

```php
public static function initialize(bool|Nette\Http\IRequest $reinit = false): void
```

--------------------------------

### Using setEmptyValue and setNullable on email field

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/base-control.md

Example of configuring an email field to treat '@' as empty and return null on empty submission.

```php
$form->addEmail('email')->setEmptyValue('@')->setNullable();
// empty submission of the @ placeholder now reads as null
```

--------------------------------

### getWrapper()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rendering.md

Resolves a 'section key' from the wrappers configuration.

```APIDOC
## [PHP] getWrapper()

### Description
Resolves a 'section key' from the wrappers configuration.

### Method
PHP method

### Endpoint
`public function getWrapper(string $name): Html`

### Parameters
#### Path Parameters
- **$name** (string) - Required - The wrapper name.

### Response
#### Success Response
- **Html** - The wrapper HTML object.
```

--------------------------------

### Blueprint::generateLatte() method signature

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/blueprint.md

Generates a Latte template blueprint. Clones the form's renderer, builds dummy controls, re-renders, and rewrites the form tag with n:name and n:ifcontent/n:foreach attributes.

```php
public function generateLatte(Form $form): string
```

--------------------------------

### Constructor

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/control-group.md

Creates an empty group backed by a WeakMap of controls, holding controls without preventing garbage collection.

```APIDOC
## Constructor

### Description
Creates an empty group backed by a `\WeakMap` of controls (controls are held without preventing GC).

### Method
`public function __construct()`

### Parameters
None.

### Return Value
No return value (constructor).
```

--------------------------------

### Adding controls with addText, addSelect, and addSubmit

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/container.md

Shows typical usage of control factories: addText with a required rule, addSelect with an optgroup and prompt, and addSubmit with an $onSubmit closure appended to onClick.

```php
$form->addText('name', 'Name:')
	->setRequired('Please fill your name.');
$form->addSelect('country', 'Country:', [
	'World' => ['bu' => 'Buranda', 'qu' => 'Qumran'],   // optgroup
	'?' => 'other',
])->setPrompt('Select your country');
$form->addSubmit('send', 'Register', function (SubmitButton $button, array $values) {
	// $onSubmit closure — appended to $button->onClick[]
});
```

--------------------------------

### ImageButton usage example

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/button-controls.md

Creates an image button with addImageButton. Clicking at coordinates (12, 34) submits map[]=12&map[]=34.

```php
$form->addImageButton('map', '/img/map.png', 'Send location');
// clicking at (12, 34) submits map[]=12&map[]=34
```

--------------------------------

### Nette\Forms\Control

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/interfaces.md

Interface that all form controls must implement. Defines methods for setting and getting values, validation, error retrieval, and omission status.

```APIDOC
## Interface: `Nette\Forms\Control`

### Description
Interface that all form controls must implement. Defines methods for setting and getting values, validation, error retrieval, and omission status.

### Methods

#### `setValue(mixed $value): static`
- Sets the control value. Implementations throw on unsuitable values.

#### `getValue(): mixed`
- Returns the current value.

#### `validate(): void`
- Runs server-side validation against all rules; on failure records errors internally.

#### `getErrors(): array`
- Returns a list of validation errors (`list<string|\Stringable>`).

#### `isOmitted(): bool`
- Returns whether the value is excluded from `$form->getValues()` result.

### Source
`src/Forms/Control.php` (line 14). Import: `use Nette\Forms\Control;`.
```

--------------------------------

### Creating groups with Form::addGroup()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/control-group.md

Shows how to create labeled and invisible groups via Form::addGroup(), set options like description, embedNext, and custom container. The second group is invisible (no visual) and uses a custom div container.

```php
$form->addGroup('Personal data')
	->setOption('description', 'We value your privacy.')
	->setOption('embedNext', true);

$form->addGroup()
	->setOption('container', Nette\Utils\Html::el('div')->id('sendBox')); // invisible subgroup
```

--------------------------------

### Programmatic ControlGroup usage

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/control-group.md

Demonstrates creating a ControlGroup directly, adding controls, and iterating over them to render labels and controls.

```php
// programmatic use:
$group = new ControlGroup;
$group->add($form['name'], $form['email']);
foreach ($group->getControls() as $control) {
	echo $control->getLabel(), $control->getControl();
}
```

--------------------------------

### DateTimeControl error handling

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/other-controls.md

Example of catching Nette\InvalidArgumentException when setting an invalid date value, with the error message 'The parsed date was invalid 'not-a-date!!''.

```php
try {
	$birth->setValue('not-a-date!!');
} catch (Nette\InvalidArgumentException $e) {
	// "The parsed date was invalid 'not-a-date!!'"
}
```

--------------------------------

### ESM entry-point exports (index.esm.ts)

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Provides a documented no-op initialize() stub and re-exports FormValidator. The initialize() function is intentionally empty.

```ts
// TODO
export function initialize() {
}
export { FormValidator };
```

--------------------------------

### getOption()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/control-group.md

Retrieves the value of a specific rendering option.

```APIDOC
## getOption()

### Description
Retrieves the value of a specific rendering option.

### Method
`public function getOption(string $key): mixed`

### Parameters
- `$key` (string) - Required - The option key.

### Return Value
Returns the option value (mixed).
```

--------------------------------

### Register custom validator with Nette.validators

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Assign a function to Nette.validators to define a custom rule. The function receives the element, arguments, and current value, and returns a boolean. This example rejects the value 'forbidden'.

```ts
Nette.validators.my_custom_check = function (elem, args, val) {
	return val !== 'forbidden';
};
```

--------------------------------

### Blueprint::latte(Form $form, bool $exit = true): void

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/blueprint.md

Generates a blueprint of the form's Latte template. Prints a self-contained HTML page with the generated {form n:name="..."} template and exits if $exit is true.

```APIDOC
## [STATIC] Blueprint::latte(Form $form, bool $exit = true): void

### Description
Generates a blueprint of the form's Latte template. Prints a self-contained HTML page (with Prism syntax highlighting) containing the generated `{form n:name="..."}` Latte template for the given form, then exits when `$exit` is true.

### Method
Static method

### Signature
`public static function latte(Form $form, bool $exit = true): void`

### Parameters
- **$form** (Form) - Required - The form to generate the blueprint for.
- **$exit** (bool) - Optional - Whether to exit after printing (default: true).

### Usage Example
```php
Nette\Forms\Blueprint::latte($form); // print blueprint & exit
```
```

--------------------------------

### UploadControl class constants and constructor

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/other-controls.md

Defines the validation rule constant Valid (with deprecated alias VALID) and the constructor. The $multiple parameter enables multi-file mode where the value becomes FileUpload[] and the name gets '[]'.

```php
/** validation rule */
public const Valid = ':uploadControlValid';
#\[\Deprecated('use UploadControl::Valid')]
public const VALID = self::Valid;

public function __construct(string|Stringable|null $label = null, bool $multiple = false)
```

--------------------------------

### initForm(form)

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/client-side.md

Initializes a form for client-side validation. Wires up event handlers for formdata, submit, and reset. Skips forms without `data-nette-rules` and sets `noValidate`.

```APIDOC
## [METHOD] initForm(form)

### Description
Wires one form: `formdata` handler for compact GET forms; skips forms without `data-nette-rules`; sets `form.noValidate = true` (unless already set); installs `submit` (cancels on failed validation) and `reset` (re-toggles) handlers.

### Method
`initForm`

### Endpoint
`initForm(form: HTMLFormElement): void`

### Parameters
- **form** (HTMLFormElement) - Required - The form element to initialize.

### Response
No return value.

### Example
```ts
v.initForm(form);
```
```

--------------------------------

### Rendering

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/base-control.md

Methods for generating HTML output for the control and its label.

```APIDOC
## Rendering

### Description
Methods for generating HTML output for the control and its label.

### Methods

#### `getControl(): Html|string`
- **Description**: Returns the HTML for the control, including name, id, required, disabled, and data-nette-rules attributes.

#### `getLabel(string|Stringable|null $caption = null): Html|string|null`
- **Description**: Returns the HTML label for the control, linking to the control's ID.

#### `getControlPart(): ?Html`
- **Description**: Returns the HTML for the control part (e.g., input element).

#### `getLabelPart(): ?Html`
- **Description**: Returns the HTML for the label part.

#### `getControlPrototype(): Html`
- **Description**: Returns the prototype for the control HTML element.

#### `getLabelPrototype(): Html`
- **Description**: Returns the prototype for the label HTML element.

#### `setHtmlAttribute(string $name, mixed $value = true): static`
- **Description**: Sets an HTML attribute on the control.

#### `setAttribute(string $name, mixed $value = true): static`
- **Description**: Deprecated. Use `setHtmlAttribute()` instead.
```

--------------------------------

### initialize(bool|Nette\Http\IRequest $reinit = false): void

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Initializes the shared Nette\Http\RequestFactory-built request for standalone (non-DI) usage. Only relevant when using Form outside Nette DI.

```APIDOC
## initialize(bool|Nette\Http\IRequest $reinit = false): void

### Description
Initializes the shared Nette\Http\RequestFactory-built request for standalone (non-DI) usage. Only relevant when using Form outside Nette DI.

### Method
PHP static method

### Signature
`public static function initialize(bool|Nette\Http\IRequest $reinit = false): void`

### Parameters
- **$reinit** (bool|Nette\Http\IRequest) - Optional - false keeps the cached default, true forces re-creation from globals, a concrete IRequest replaces it.

### Return Value
void
```

--------------------------------

### Generated initialize() body for constant key

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/forms-di.md

Shows the code generated inside the DI container's initialize() method when the key matches a Nette\Forms\Form constant. The constant is resolved at compile time.

```php
Nette\Forms\Validator::$messages[Nette\Forms\Form::<Name>] = '<text>';
```

--------------------------------

### getMethod(): string

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Returns the HTTP method used for form submission.

```APIDOC
## getMethod(): string

### Description
Returns the HTTP method used for form submission.

### Method
PHP method

### Signature
`public function getMethod(): string`

### Returns
- **string** - The HTTP method.

```

--------------------------------

### renderPair()

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rendering.md

Builds a pair container consisting of renderLabel() and renderControl() with state classes and control options.

```APIDOC
## [PHP] renderPair()

### Description
Builds a pair container consisting of renderLabel() and renderControl() with state classes and control options.

### Method
PHP method

### Endpoint
`public function renderPair(Nette\Forms\Control $control): string`

### Parameters
#### Path Parameters
- **$control** (Nette\Forms\Control) - Required - The control to render.

### Response
#### Success Response
- **string** - The rendered HTML string.
```

--------------------------------

### Internal reflection and ini helper method signatures

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/helpers.md

Internal methods: iniGetSize() parses PHP ini size values (e.g., '2M' to 2097152) with k/m/g units; getSingleType() returns the single type name from reflection or null, throwing Nette\InvalidStateException for unsupported union/intersection types; tryEnumConversion() converts a value to a BackedEnum case when the reflection type is a backed enum; getSupportedImages() returns MIME types of image types supported by Nette\Utils\Image.

```php
/** @internal */
public static function iniGetSize(string $name): int

/**
 * Returns the single type name from reflection, or null if no type is defined.
 * @internal
 */
public static function getSingleType(\ReflectionParameter|\ReflectionProperty $reflection): ?string

/** @internal */
public static function tryEnumConversion(
	mixed $value,
	\ReflectionParameter|\ReflectionProperty|null $reflection,
): mixed

/**
 * @internal
 * @return list<string>
 */
public static function getSupportedImages(): array
```

--------------------------------

### Form method, action, and attribute methods

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Methods for setting and getting the form's action URL, HTTP method, and HTML attributes. setMethod() throws Nette\InvalidStateException if called after HTTP data has been received. The element prototype defaults to <form action="" method="post">.

```php
public function setAction(string|Stringable $url): static
public function getAction(): string
public function setMethod(string $method): static
public function getMethod(): string
public function isMethod(string $method): bool
public function setHtmlAttribute(string $name, mixed $value = true): static
public function getElementPrototype(): Html
```

--------------------------------

### render() method signature

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/rendering.md

Main entry point for complete form rendering. Accepts an optional mode parameter to render specific parts: 'begin', 'errors', 'ownerrors', 'body', 'end', or empty to render all.

```php
/**
 * Provides complete form rendering.
 * @param  ?string  $mode  'begin', 'errors', 'ownerrors', 'body', 'end' or empty to render all
 */
public function render(Nette\Forms\Form $form, ?string $mode = null): string
```

--------------------------------

### createInputList() and createSelectBox() method signatures

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/helpers.md

createInputList() generates an HTML list of labeled inputs (radio buttons or checkboxes) with optional wrapper element. createSelectBox() generates a <select> element with <option>s and nested <optgroup>s; $selected marks the selected option. Dynamic attribute keys ending in ':' (per-item values) and '?' (boolean) are resolved per item.

```php
/**
 * Generates an HTML list of labeled inputs (radio buttons or checkboxes).
 * @param  mixed[]  $items  value => label pairs
 * @param  ?array<string, mixed>  $inputAttrs
 * @param  ?array<string, mixed>  $labelAttrs
 */
public static function createInputList(
	array $items,
	?array $inputAttrs = null,
	?array $labelAttrs = null,
	Html|string|null $wrapper = null,
): string

/**
 * Generates a <select> HTML element from the items array.
 * @param  mixed[]  $items
 * @param  ?array<string, mixed>  $optionAttrs
 */
public static function createSelectBox(array $items, ?array $optionAttrs = null, mixed $selected = null): Html
```

--------------------------------

### RadioList usage with setValue, checkDefaultValue, setDisabled

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/choice-controls.md

Example of a radio list. setValue('m') succeeds, setValue('x') throws Nette\InvalidArgumentException. After checkDefaultValue(false), setValue('x') silently stores 'x' but getValue() returns null. setDisabled(['f']) disables the 'f' item, which then reads as null.

```php
$radio = $form->addRadioList('gender', 'Gender', ['m' => 'male', 'f' => 'female']);
$radio->setValue('m');             // ok
$radio->setValue('x');             // Nette\InvalidArgumentException
$radio->checkDefaultValue(false);  // then setValue('x') silently stores 'x', getValue() → null
$radio->setDisabled(['f']);        // 'f' disabled per-item, reads as null
```

--------------------------------

### CheckboxList public methods

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/choice-controls.md

Public API of the CheckboxList control. loadHttpData() reads the name without trailing '[]' and explodes comma-separated strings for GET data-nette-compact submissions. getControl() rebuilds the list, attaching data-nette-rules to the first item only and merging per-item disabled. getLabel() removes the 'for' attribute.

```php
public function __construct(string|Stringable|null $label = null, ?array $items = null)
public function loadHttpData(): void
public function getControl(): Html
public function getLabel(string|Stringable|null $caption = null): Html
public function getControlPart(int|string|null $key = null): Html
public function getLabelPart(int|string|null $key = null): Html
public function getSeparatorPrototype(): Html
public function getContainerPrototype(): Html
public function getItemLabelPrototype(): Html
```

--------------------------------

### getAction(): string

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/form.md

Returns the form's action URL as a string.

```APIDOC
## getAction(): string

### Description
Returns the form's action URL as a string.

### Method
PHP method

### Signature
`public function getAction(): string`

### Returns
- **string** - The action URL.

```

--------------------------------

### Latte template for form rendering

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/latte.md

Use this Latte template to render a form with error display, labels, inputs, and error messages. The form is named 'signup' and uses n:name, n:ifcontent, n:foreach, and Latte macros like {label}, {input}, and {inputError}.

```latte
<form n:name="signup">
	<ul class="error" n:ifcontent>
		<li n:foreach="$form->ownErrors as $error">{$error}</li>
	</ul>
	{label name/}
	{input name, class => 'form-control'}
	{inputError name}
	{input submit}
</form>
```

--------------------------------

### generateHtmlName() and exportRules() method signatures

Source: https://github.com/nette/forms/blob/master/_autodocs/api-reference/helpers.md

generateHtmlName() converts a component name like 'form-person-name' to 'person[name]' by replacing the separator. Unsafe names (e.g., 'attributes', 'submit', 'form') get a '_' prefix. exportRules() serializes a Rules tree into JSON for data-nette-rules; non-exportable rules cause an early break, branches become {op, rules, control, toggle}, leaves {op, msg}.

```php
public static function generateHtmlName(string $id): string
public static function exportRules(Rules $rules): array
```
Tokens:
Raw