Skip to content
Nucleus Docs

Form

<ns-form>
Overview Guidance Implementation

Overview

Form is used to contain inputters and manage their validations and data.

✨ This is an auto-generated AI summary of the ns-form's documentation. It may not be accurate. ✨

The ns-form component mimics the native form element features. Its purpose is to allow customers to provide data and validate it before sending them to processing.

Examples

Configure

Guidance

Implementation

Placement

The ns-form component can be used in the following components:

Specification

Attributes

type
Property
type
Type
string
Default
standard

Slots

SlotPermitted tagsDescription
Anonymous slot<ns-inputter> <ns-datepicker> <ns-appointment-picker> <nsx-address-selector> <ns-password> <ns-form-group> <ns-cta> The anonymous slot for form elements.

Events

NameDescription
validatedDispatched when the form is validated. It holds the `ValidityState` object.
submitDispatched when the form is validated and submitted. It holds the `submitter` element.

Specification notes

Form validation

When the form is submitted, the form elements within the <ns-form> are validated against their respective validation list and validated event is triggered. The validated event holds the validation data.

Validation data

An invalid validate return response looks like:

{
  "isValid": false,
  "fields": [
    {
      "name": "email-address",
      "isValid": false,
      "value": "",
      "error": "This field is required",
      "input": {}
    },
    {
      "name": "password",
      "isValid": false,
      "value": "",
      "error": "This field is required",
      "input": {}
    }
  ],
  "fieldsByName": {
    "email-address": {
      "name": "email-address",
      "isValid": false,
      "value": "",
      "error": "This field is required",
      "input": {}
    },
    "password": {
      "name": "password",
      "isValid": false,
      "value": "",
      "error": "This field is required",
      "input": {}
    }
  }
}

A valid validate return response looks like:

{
  "isValid": true,
  "fields": [
    {
      "name": "email-address",
      "isValid": true,
      "value": "[email protected]",
      "input": {}
    },
    {
      "name": "password",
      "isValid": true,
      "value": "password12",
      "input": {}
    }
  ],
  "fieldsByName": {
    "email-address": {
      "name": "email-address",
      "isValid": true,
      "value": "[email protected]",
      "input": {}
    },
    "password": {
      "name": "password",
      "isValid": true,
      "value": "password12",
      "input": {}
    }
  }
}
Submit event

The submit event is triggered in one of two ways:

  • Clicking on <ns-cta> (without href attribute).
  • Pressing enter when there is only one input in the form.

To handle the submit event either add onsubmit callback or add an event listener to <ns-form>.

The event contains event.detail.submitter, the element that triggered the <ns-form> submit.

onsubmit example:

<ns-form onsubmit="submittedForm(event)">
  <ns-inputter validation='["isRequired"]'>
    ...
  </ns-inputter>
  <ns-cta type="submit">Submit</ns-cta>
</ns-form>


<script>
  // do something as a result of the event
  function submittedForm(event) {


  }
</script>

Last updated: