Form

Kickstand UI's <ks-form> element has all of the same behavior a standard form element has, but with some additional features that make validation and submission easier.

Most of the properties (action, enctype, method, and target) are standard form attributes and you can read more about them from the MDN documentation (opens new window).

Submit Me

<ks-form>
    <ks-form-field label="Name" required></ks-form-field>
    <ks-form-field label="Email" type="email" value="bad.email"></ks-form-field>
    <ks-button type="submit">Submit Me</ks-button>
</ks-form>

Inline Forms

Occasionally there is a need to simplify forms and combine the input and submit button into a single line.

<ks-form>
    <ks-form-field label="Search" type="search" placeholder="Search..." hide-label></ks-form-field>
    <ks-button type="submit">
        <ks-icon icon="search" label="search"></ks-icon>
    </ks-button>
</ks-form>

Styling Forms

The form is designed to stand out from the other content in order to increase conversion. Styling forms is easy using CSS, but you can also easily do os using utility classes. The follow example removes the border, background, and padding from the form, but similar utility classes could be used to create custom form styles.

<ks-form class="p-none b-none bg-transparent" inline>
    <ks-form-field label="Search" type="search" placeholder="Search..." hide-label></ks-form-field>
    <ks-button type="submit">
        <ks-icon icon="search" label="search"></ks-icon>
    </ks-button>
</ks-form>

Submission

In a standard HTML form, submission causes the page to reload. In Kickstand UI's forms, that behavior is prevented by default to allow for client-side validation and precessing, but if the action property is populated, the default behavior will resume.

Forms can be submitted with a submit button, but can also be submitted programmatically using the submit method. When executing the submit method, the form will also perform form validation and emit the submitted event.

To collect form data easily, a custom event emitter has been added to provide field data and validation information - submitted. Below is an example of the form data (type IFormData) provided by the event for the form above:

{
    isValid: false,
    formData: {
        name: "",
        email: "bad.email"
    },
    formFieldData: [
        {
            name: "name",
            value: "",
            isValid: false,
            validity: {
                badInput: false,
                customError: false,
                patternMismatch: false,
                rangeOverflow: false,
                rangeUnderflow: false,
                stepMismatch: false,
                tooLong: false,
                tooShort: false,
                typeMismatch: false,
                valid: false,
                valueMissing: true
            }
        },
        {
            name: "email",
            value: "bad.email",
            isValid: false,
            validity: {
                badInput: false,
                customError: false,
                patternMismatch: false,
                rangeOverflow: false,
                rangeUnderflow: false,
                stepMismatch: false,
                tooLong: false,
                tooShort: false,
                typeMismatch: true,
                valid: false,
                valueMissing: false
            },
        }
    ]
}

Getting Form Data

Getting this data is simple as setting up a standard event listener.

<ks-form id="my_form">
    <ks-form-field label="Name" required></ks-form-field>
    <ks-form-field label="Email" type="email"></ks-form-field>
    <ks-button type="submit">Submit Me</ks-button>
</ks-form>
<script>
    $('my_form').on('submitted', (e) => {
        let myFormData = e.detail;
        // do something with the form data
    });
</script>

Note

If you are using a JavaScript framework, your implementation may vary. Be sure to review the documentation for event listening best practices.

This example uses Kickstand UI's DOM Utilities to help keep the code dimple and easy to read.

Clearing Forms

When a user cancels and action, closes a modal with a form in it, or backs out of a process, you may want to reset a form so it is fresh and clean the next time the user comes to the form. You can easily do the with the clear method. This will reset the form and restore its pristine condition.

Whenever a form is cleared or reset, you can listen for the event using the cleared event listener.

Validation

When the form is submitted, each of the fields will be validated. If any of the fields are invalid, the form's state will be set to "invalid" and an error message will appear at the bottom of the form. You can customize this error message using the error-message property.

You can also manually change the validation state of you form by using the invalid property.

WARNING

Client-side validation is not a replacement for server-side validation. Be sure that you also validate data coming from the client on the server to insure data integrity and the safety of your application.

Accessibility

The form itself is fairly straight forward, but one point of interest for accessibility is that the form error message is using the <ks-alert> component, which means that it has the role="alert" as well as the aria-live="assertive".

The error message will also be accompanied by an icon for those users that are not able to distinguish the error from the colored text.

Properties

Property	Attribute	Description	Type	Default
inline	inline	toggles the inline layout of the form	boolean	false
action	action	The URL that processes the form submission.	string	undefined
enctype	enctype	This is the MIME type of the form submission	string	'One or more of the from fields are not valid. Please, review the form and try again.'
errorMessage	error-message	The message that displays at the footer of the form if there is a validation problem	string	'One or more of the from fields are not valid. Please, review the form and try again.'
invalid	invalid	toggles the validity of the form	boolean	false
method	method	The HTTP method to submit the form with.	"get" or "post"	undefined
target	target	Indicates where to display the response after submitting the form.	"_blank", "_parent", "_self", or "_top"	undefined

Events

Event	Description	Type
submitted	the event emitted when the form is submitted	CustomEvent<IFormData>
cleared	the event emitted when the form is cleared or reset	CustomEvent

Methods

clear() => Promise<void>

This will clear all form values and reset any error messages.

Returns

Type: Promise<void>

submit() => Promise<void>

This will perform validation and emit the submitted event.

Returns

Type: Promise<void>