Form Component

Handling user input through forms is fundamental to many applications. Forms enable users to log in, update profiles, enter sensitive information, and perform various data-entry tasks.

The Form component is based on Angular template-driven forms.

Composition

The Form is a container that can include Form Controls such as Checkbox, Datetime, Input, Radiogroup, Range, Select, and Toggle.

To create a Form Control, drag and drop a component from the PALETTE and place it inside the Form. You'll then see the Form Control section with additional control properties:

🚧

Important

A component becomes a Form Control only when the Name property is specified, which defines the control's data key.

For example, if you have an Input with Name = userName and value = Peter, the control data will be available as a property of the form data object: {userName: 'Peter'}.

Sending Data

There are two ways to send form data:

1. Using a Submit control - The control must be placed inside the form:

<form>
    <ion-button type="submit">Submit</ion-button>
</form>

2. Using the Form submit action - Available on the EVENTS tab. The control can be placed anywhere on the page.

Form Submission Actions

Actions for form submission can be specified in three ways:

1. Form submit event (for beginners) - Use the form component's Form submit event on the EVENTS tab. Choose an action to execute when the form is submitted, such as Invoke service (e.g., Login service) with specified mapping on the DATA panel.

2. (ngSubmit) event (for advanced users) - Define a custom function handler that executes the submission from custom code.

3. Action property (for advanced users) - Define the URL where form data will be sent.

Validation

By default, Ionic provides built-in validation rules for form controls. To use the form's overall validity, specify the Form ID property.

The value passed as the Form ID property can be used as a variable containing form information, as described in the PROPERTIES section. The Form ID property can be used as a variable containing the Form state (e.g., formID.valid and formID.value). To use it in custom code, add the 'this.' prefix.

👍

Validation Component

For UI components that don't automatically get validation properties when included in a Form, or are difficult to combine for validation purposes, use the Validation component.

👍

Datetime Validation Customization Video Tutorial

You can also check this YouTube video to learn how to use the plugin, make date fields required and ensure user input, and see how the Validation component works within the Form container for reliable datetime checks:

Form and Control States

Form and Controls have different states when using Ionic validation:

Validation Examples

You can check the invalid input state to show an error message:

<ion-text *ngIf="user.invalid" color="danger">Incorrect user name</ion-text>

In this example, user is a Control ID defined for the Input component.

For specific validation errors, use the errors state with the validation error type.

Here's how to display different error messages for Input component validation:

1. Define the Control ID property of the Input as passControl
2. Set validation rules (e.g., required and pattern="[0-9]*")
3. Add error message components with the *ngIf directive

<form #myForm="ngForm">
    <ion-input required pattern="[0-9]*" #passControl="ngModel" [ngModel] name="pass"></ion-input>
    <ion-text *ngIf="passControl.errors && passControl.errors.required" color="danger">
        Value must be entered
    </ion-text>
    <ion-text *ngIf="passControl.errors && passControl.errors.pattern" color="danger">
        Value should contain only numbers
    </ion-text>
</form>

If the component is valid, passControl.errors returns null (equivalent to false). If invalid, it returns an object containing all validation errors accessible by their names.

📘

Want to know more?

More details with examples about the Validation property can be found here.

👍

Datetime Validation Customization Video Tutorial

You can also check this YouTube video to learn how to use the plugin, make date fields required and ensure user input, and see how the Validation component works within the Form container for reliable datetime checks:

Properties

🚧

Important Note

This document lists properties specific to this UI component. For properties common to most UI components, see the General components document.

Common Properties

🚧

Note

In the component's initial state, default HTML <form> features (Action, Target, etc.) are not supported because they're replaced with Angular functionality. To disable Angular functionality and enable default HTML behavior, enable the Native validation property.

Using Form ID

The Form ID property can be used in templates or code as a variable containing information about the form:

formID = {
    value: boolean,   // Reports the value of the form
    valid: boolean,   // Reports whether the form is valid
    invalid: boolean, // Reports whether the form is invalid
    dirty: boolean    // Reports whether the form is dirty
}

In templates, use the Form ID property as a variable. It can also be passed as a function argument:

<ion-button disabled={{formID.invalid}} type="submit">Submit</ion-button>
<ion-button (click)="send(formID)">Send</ion-button>

To use in custom code, the variable is available as this.<Form ID>:

if (this.formID.valid) this.submit();