Hooks

This library offers a way of hooking into the logic of the form fields. Hooks that validate input and display error messages, also ship with built-in translations in all 12 supported languages (opens in a new tab). Below you can find the list of all official hooks and their documentation. Please note, however, that you can also write your own hooks if needed.

Usage

All hooks are functions, that can take 0 or more arguments. They are returned within the hooks property of any form field, such as:

const formFields = {
  name: {
    label: 'Name',
    hooks: [useAutoCapitalize(), useLength(2, 155), useRequired()]
  }
}

List of hooks

useAutoCapitalize

This hook will automatically capitalize the first letter of each word in the input value. The hook is not configurable.

import { useAutoCapitalize } from '@phormal/core'
 
const formFields = {
  name: {
    label: 'Name',
    hooks: [useAutoCapitalize()]
  }
}

useEmail

This hook will validate that the input is a valid email address. The hook is not configurable.

import { useEmail } from '@phormal/core'
 
const formFields = {
  email: {
    label: 'Email',
    hooks: [useEmail()]
  }
}

useLength

This hook can validate the minimum and maximum length on the input of a field.

Argument	Type	Description
`minLength`	`number`, `undefined` or `null`	Set the minimum length of the input
`maxLength`	`number`, `undefined` or `null`	Set the maximum length of the input

import { useLength } from '@phormal/core'
 
const formFields = {
  name: {
    label: 'Name',
    hooks: [useLength(null, 10)] // no minimum length, maximum length of 10
  },
  description: {
    label: 'Description',
    hooks: [useLength(10, 100)] // minimum length of 10, maximum length of 100
  },
  address: {
    label: 'Address',
    hooks: [useLength(10)] // minimum length of 10, no maximum length
  }
}

useMinMax

This hook allows you to validate the minimum and maximum value of a number input.

Argument	Type	Description	Required
`minValue`	`number`, `undefined` or `null`	Set the minimum value of the input	Yes
`maxValue`	`number`, `undefined`	Set the maximum value of the input	No

import { useMinMax } from '@phormal/core'
 
const formFields = {
  age: {
    label: 'Name',
    type: 'number',
    hooks: [useMinMax(1, 200)] // minimum value of 1, maximum value of 1000
  },
  price: {
    label: 'Price',
    type: 'number',
    hooks: [useMinMax(10)] // minimum value of 10, no maximum value
  },
  quantity: {
    label: 'Quantity',
    type: 'number',
    hooks: [useMinMax(null, 100)] // no minimum value, maximum value of 100
  }
}

useUrl

This hook will validate a url. The hook optionally takes a configuration object, with two properties allowedHosts, and allowedProtocols, as in the examples below.

import { useUrl } from '@phormal/core'
 
const formFields = {
  url: {
    label: 'Email',
    hooks: [useUrl()] // validates that the input is a valid url
  },
  urlInvalidHost: {
    label: 'URL with valid host',
    hooks: [useUrl({ allowedHosts: ['google.com', 'google.nl', 'google.be'] })] // validates that the input is a valid url and that the host is one of the allowed hosts
  },
  urlInvalidProtocol: {
    label: 'URL with valid protocol',
    hooks: [useUrl({ allowedProtocols: ['https'] })] // validates that the input is a valid url and that the protocol is one of the allowed protocols
  }
}

useRegex

This hook can validate the input of a field against a regular expression. It can also, optionally, help you display an error message showing your user what format is expected.

Argument	Type	Description	Required
`regex`	`RegExp`	The pattern that the input has to match	Yes
`readableExpectedFormat`	`string`	A string to display in your error message, for users to visualize what the expected input looks like	No

import { useRegex } from '@phormal/core'
 
const formFields = {
  orderNumber: {
    label: 'Order Number',
    hooks: [useRegex(/PH-\d{8}/)] // only allow order numbers that start with PH- and have 8 digits
  },
  orderNumberFriendlyErrpr: {
    label: 'Order Number',
    hooks: [useRegex(/PH-\d{8}/), 'PH-XXXXXXXX'] // same as above, but will display the expected format to the user in the error message
  },
}

useRequired

This hook will validate that the input is not empty. The hook is not configurable.

import { useRequired } from '@phormal/core'
 
const formFields = {
  name: {
    label: 'Name',
    hooks: [useRequired()]
  }
}

useValidZip

This hook will validate that the format of a postal code matches the required format for a given country. The hook is not configurable, but requires 2 things to work properly:

It can only be used on a field of type text (which is the default for any field, if not specified)
It needs the presence of another field named country. This field needs a value that matches a valid country code, according to the ISO-3166 Alpha-2 standard: https://www.iso.org/obp/ui/#search/code/ (opens in a new tab)

import { useValidZip } from '@phormal/core'
 
const formFields = {
  country: {
    type: 'select',
    label: 'Country',
    hooks: [useRequired()],
    value: 'DE',
    options: [
      {value: 'US', label: 'United States'},
      {value: 'CA', label: 'Canada'},
      {value: 'MX', label: 'Mexico'},
      {value: 'FR', label: 'France'},
      {value: 'DE', label: 'Germany'}
    ]
  },
  zip: {
    label: 'ZIP code',
    hooks: [useValidZip()]
  }
}

Last updated on January 21, 2023

Themes Customization