Skip to main content

Validation

Basics​

Kingpin's validation mechanism is very easy and it is totally driven by the single responsibility principle.

Each form element contains its validation policy and validate itself.

Each field can have the optional validation props which could be:

  • a function
  • an array of functions.
  • an object key:function
note

The function passed has to take as argument the element value and to return a boolean value.

So basically to validate a simple input you can:

import { Form, Input } from 'kingpin-react-form'

const shouldNotBeEmpty = (s: string): boolean => s.length > 0
const shouldBeAtLeast10Chars = (s: string): boolean => s.length > 10

function App(): JSX.Element {
  return (
    <Form>
      <Input name="email" type="email" validation={shouldNotBeEmpty} />
      <Input name="password" type="password" validation={[shouldNotBeEmpty, shouldBeAtLeast10Chars]} />
      <button type="submit">Submit</button>
    </Form>
  )
}

You can still use all the native HTML validation attributes and also use them together with your custom functions.

Error handling​

Validation is very useful expecially when you want to display meaningful messages to the users.

For this reason the validation mechanism is strongly bond to the <Error /> component (check here for more) and it's encouraged to use them together.

note

All the error examples show below are complementary. You can use them all together.

So the validation example above it could be extended in:

import { Error, Form, Input } from 'kingpin-react-form'

const shouldNotBeEmpty = (s: string): boolean => s.length > 0
const shouldBeAtLeast10Chars = (s: string): boolean => s.length > 10

function App(): JSX.Element {
  return (
    <Form>
      <Input name="email" type="email" validation={shouldNotBeEmpty} />
      <Error name="email:error">The email field is mandatory</Error>
      <Input name="password" type="password" validation={[shouldNotBeEmpty, shouldBeAtLeast10Chars]} />
      <Error name="password:error">Please set a stronger password.</Error>
      <button type="submit">Submit</button>
    </Form>
  )
}

Multiple errors​

Is quite usual have different messages for different invalid fields. That's exactly the reason why you can pass as validation prop an objects of functions.

You can use the keys of your validation object to create more atomic error messages.

import { Error, Form, Input } from 'kingpin-react-form'

const shouldNotBeEmpty = (s: string): boolean => s.length > 0
const shouldBeAtLeast10Chars = (s: string): boolean => s.length > 10

function App(): JSX.Element {
  return (
    <Form>
      <Input
        name="password"
        type="password"
        validation={{
          empty: shouldNotBeEmpty,
          tenChars: shouldBeAtLeast10Chars,
        }}
      />
      <Error name="password:tenChars">Password should be at least 10 characters</Error>
      <Error name="password:empty">Password shouldn't be emtpy.</Error>
      <button type="submit">Submit</button>
    </Form>
  )
}

Global error​

In order to display a global message when the form is invalid in a unspecified field you can just use the name="error" to trigger it.

import { Error, Form, Input } from 'kingpin-react-form'

const shouldNotBeEmpty = (s: string): boolean => s.length > 0
const shouldBeAtLeast10Chars = (s: string): boolean => s.length > 10

function App(): JSX.Element {
  return (
    <Form>
      <Input name="email" type="email" validation={shouldNotBeEmpty} />
      <Input name="password" type="password" validation={[shouldNotBeEmpty, shouldBeAtLeast10Chars]} />
      <Error name="error">The form is invalid. Please check the fields above.</Error>
      <button type="submit">Submit</button>
    </Form>
  )
}

Error className​

Each kingpin element accepts as prop errorClassName which is internally merged to the className prop when the element doesn't satisfy its validation policy.

note

The element className is updated during the form submit.

import { Form, Input } from 'kingpin-react-form'

const shouldNotBeEmpty = (s: string): boolean => s.length > 0
const shouldBeAtLeast10Chars = (s: string): boolean => s.length > 10

function App(): JSX.Element {
  return (
    <Form>
      <Input name="email" type="email" validation={shouldNotBeEmpty} className="email" errorClassName="email-error" />
      <Input
        name="password"
        type="password"
        validation={[shouldNotBeEmpty, shouldBeAtLeast10Chars]}
        className="password"
        errorClassName="password-error"
      />
      <button type="submit">Submit</button>
    </Form>
  )
}