Forms and dates

useFormValidation

Enhances native HTML form validation with custom error messages via data-error-* attributes, live field description syncing, and programmatic validity control.

Copy React example Form component

Live component preview · Astro

Explore Form

Try the component this hook connects to. The preview uses the Astro adapter; the React example below uses useFormValidation.

React usage

Import from @santi020k/lumen-react and spread the controller props onto the matching components.

import { Button, Field, Input, Label } from '@santi020k/lumen-react'
import { useFormValidation } from '@santi020k/lumen-react'

export function SignupForm() {
  const form = useFormValidation({
    onValid: () => console.log('Form is valid'),
    onInvalid: ({ controls }) =>
      console.log('Invalid fields:', controls?.length)
  })

  return (
    <form {...form.formProps}>
      <Field>
        <Label htmlFor="email">Email</Label>
        <Input
          id="email"
          type="email"
          required
          data-error-required="Please enter your email"
          data-error-type="Enter a valid email address"
        />
      </Field>
      <Button type="submit">Sign up</Button>
    </form>
  )
}

import { Button, Field, Input, Label } from '@santi020k/lumen-react'
import { useFormValidation } from '@santi020k/lumen-react'

export function SignupForm() {
  const form = useFormValidation({
    onValid: () => console.log('Form is valid'),
    onInvalid: ({ controls }) =>
      console.log('Invalid fields:', controls?.length)
  })

  return (
    <form {...form.formProps}>
      <Field>
        <Label htmlFor="email">Email</Label>
        <Input
          id="email"
          type="email"
          required
          data-error-required="Please enter your email"
          data-error-type="Enter a valid email address"
        />
      </Field>
      <Button type="submit">Sign up</Button>
    </form>
  )
}

Load @santi020k/lumen-react/styles.css once in your application. With React Server Components, put 'use client' at the top of the module that calls the hook. Follow the React setup guide for the framework boundary.

Options

Property	Type	Default	Description
onValidate	(detail: FormValidationValidateDetail) => void	-	Callback fired when a single control is validated.
onValid	(detail: FormValidationStateDetail) => void	-	Callback fired when the form becomes valid.
onInvalid	(detail: FormValidationStateDetail) => void	-	Callback fired when the form has invalid controls.

Controller return values

Property	Type	Description
formProps	LumenProps<"form">	Spread onto the <form> element. Adds native validation bypass and submit handler.
formRef	RefObject<HTMLFormElement>	Ref to the form element.
getControls	(form?) => NativeFormControl[]	Returns all form controls, including inputs, selects, and text areas.
setFieldValidity	(control, invalid, message?) => void	Programmatically set a field as valid or invalid with a custom message.
validateControl	(control, form?) => boolean	Validate a single control and return whether it is valid.
validateForm	(form?) => NativeFormControl[]	Validate all controls and return the array of invalid controls.