Form

High-performance form component with data domain management. Includes data entry, validation, and corresponding styles.
Import
Source components/form
Docs Edit this page

When To Use#

  • When you need to create an instance or collect information.
  • When you need to validate fields in certain rules.

Form is totally based on Angular Forms, you can use reactive forms or template-driven-forms. Please make sure you have read the official form document before using the component.

Form#

You can align the controls of a form using the layout prop：

  • horizontal：to horizontally align the labels and controls of the fields. (Default)
  • vertical：to vertically align the labels and controls of the fields.
  • inline：to render form fields in one line.

nz-form-item#

Used to separate the item in forms, contains label(optional) and control field.

nz-form-label#

The label of the form item, optional.

nz-form-control#

A form consists of one or more form fields whose type includes input, textarea, checkbox, radio, select, tag, and more.

<form nz-form>
  <nz-form-item>
    <nz-form-label [nzSpan]="6" nzFor="email">E-mail</nz-form-label>
    <nz-form-control [nzSpan]="14">
      <input nz-input name="email" type="email" id="email" />
    </nz-form-control>
  </nz-form-item>
</form>

Examples

Inline Login Form

Inline login form is often used in navigation bar.

expand codeexpand code
      Loading...
Login Form

Normal login form which can contain more elements.

expand codeexpand code
      Loading...
+86
We must make sure that your are a human.
Registration

Fill in this form to create a new account for you.

expand codeexpand code
      Loading...
Dynamic Form Item

Add or remove form items dynamically.

expand codeexpand code
      Loading...
Reactive Forms Validation

We provide properties like nzValidateStatusnzHasFeedback in nz-form-control to customize your own validate status and message, when using reactive forms.

  1. nzValidateStatus: validate status of form components, the default status comes from the NgControl in nz-form-control, you can set other NgControl to it.
  2. nzHasFeedback: display feed icon of input control
  3. nzSuccessTipnzWarningTipnzErrorTipnzValidatingTip：display validate message。

When there are multiple tips in the same state, nzSuccessTipnzWarningTipnzErrorTipnzValidatingTip supports the passing TemplateRef<{ $implicit: FormControl } type, which can be used to switch tips after exporting FormControl via the template syntax. When the FormControl.status is INVALID, and the errors contains {warning:true} , the nz-form-control display with warning status.

expand codeexpand code
      Loading...
Template-driven Forms Validation

When using template-driven forms, the form could change its status via the template setting.

  1. nzHasFeedback: display feed icon of input control
  2. nzSuccessTipnzWarningTipnzErrorTipnzValidatingTip: display validate message。

When there are multiple tips in the same state, nzSuccessTipnzWarningTipnzErrorTipnzValidatingTip supports the passing TemplateRef<{ $implicit: NgModel } type, which can be used to switch tips after exporting NgModel via the template syntax.

expand codeexpand code
      Loading...
Auto tips

Make tips to be easy.
Need to customize Validators and provide nzAutoTips in advance, the priority is as follows:

  • Validators > nzAutoTips
  • Via @Input set nzAutoTips
  • Via global config set nzAutoTips

In addition, you can use nzDisableAutoTips to disable it.

Via the current locale (zh-cn, en...) is used as the key of nzAutoTips to search for tips. If it is not found, it will be searched again with default.

expand codeexpand code
      Loading...
Option 1
Option 2
Manual Set Validation Status

You can set the form status directly via the nzValidateStatus on nz-form-control.

  1. nzValidateStatus: validate status of form components which could be 'success', 'warning', 'error', 'validating'.
  2. nzHasFeedback: display feed icon of input control
  3. nzSuccessTipnzWarningTipnzErrorTipnzValidatingTip：display validate message。
expand codeexpand code
      Loading...
Select a option and change input text above
Coordinated Controls

Use setValue to set other control's value programmaticly.

expand codeexpand code
      Loading...
Form Layout

There are three layout for form: horizontal, vertical, inline.

expand codeexpand code
      Loading...
Dynamic Rules

Perform different check rules according to different situations.

expand codeexpand code
      Loading...
Label can wrap

Turn on nzLabelWrap to wrap label if text is long.

expand codeexpand code
      Loading...
Text align of form label

text align of form label.

expand codeexpand code
      Loading...

API#

[nz-form]#

PropertyDescriptionTypeDefault ValueGlobal Config
[nzLayout]Form layout'horizontal' | 'vertical' | 'inline''horizontal'
[nzAutoTips]Set default props [nzAutoTips] value of nz-form-control, please refer to the example: Auto tipsRecord<string, Record<string, string>>{}✅
[nzDisableAutoTips]Set default props [nzDisableAutoTip] value of nz-form-controlbooleanfalse✅
[nzNoColon]Set default props [nzNoColon] value of nz-form-labelbooleanfalse✅
[nzTooltipIcon]Set default props [nzTooltipIcon] value of nz-form-labelstring | { type: string; theme: ThemeType }{ type: 'question-circle', theme: 'outline' }✅
[nzLabelAlign]Set default props [nzLabelAlign] value of nz-form-label'left' | 'right''right'
[nzLabelWrap]Set default props [nzLabelWrap] value of nz-form-labelbooleanfalse

nz-form-item#

Used to separate the item in forms, contains label(optional) and control field.

All api in nz-row can be used in nz-form-item.

nz-form-label#

The label of the form item, optional.

All api in nz-col can be used in nz-form-label.

PropertyDescriptionTypeDefault Value
[nzRequired]add required style to current itembooleanfalse
[nzNoColon]whether to not display : after label text.booleanfalse
[nzFor]The for property of labelstring-
[nzTooltipTitle]Set tooltip infostring | TemplateRef<void>-
[nzTooltipIcon]Set icon of tooltip infostring | NzFormTooltipIcon-
[nzLabelAlign]The text align of label'left' | 'right''right'
[nzLabelWrap]whether label can be wrapbooleanfalse

nz-form-control#

Note：Due to the lack of partial Observable in Angular Form, you have to notify nz-form-control to update its status with updateValueAndValidity when you update form status using methods like markAsDirty.

A form consists of one or more form fields whose type includes input, textarea, checkbox, radio, select, tag, and more.

All api in nz-col can be used in nz-form-control.

PropertyDescriptionTypeDefault Value
[nzValidateStatus]Will generate status based on the input FormControl, NgModel or string, the default value is the first FormControl or NgModel in nz-form-control'success' | 'warning' | 'error' | 'validating' | FormControl | NgModelfirst FormControl or NgModel in nz-form-control
[nzHasFeedback]Used with nzValidateStatus, this option specifies the validation status icon. Recommended to be used only with Input.booleanfalse
[nzExtra]The extra prompt messagestring | TemplateRef<void>-
[nzSuccessTip]Tip display when validate successstring | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzWarningTip]Tip display when validate warningstring | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzErrorTip]Tip display when validate errorstring | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzValidatingTip]Tip display when validatingstring | TemplateRef<{ $implicit: FormControl | NgModel }>-
[nzAutoTips]The object of the tips, please refer to the example: Auto tipsRecord<string, string | Record<string, string>>-
[nzDisableAutoTips]Disable Auto Tipsboolean-

nz-form-split#

The split icon of -

nz-form-text#

Text in nz-form-control