Validation

DYONA Form has three related, distinct validation mechanisms:

1. required, a direct field property.
2. validations, an array of declarative rules.
3. Built-in validation for particular field types: type: 'email' and type: 'password' with passwordRules.

Try it live

Want to see these validation rules in action?

Open Validation in the Lab →

required

Set required: true to make a field mandatory:

{
  name: 'username',
  label: 'Username',
  type: 'text',
  required: true
}

The declarative equivalent is {type: 'required'} inside validations. That form can customize the error with message:

{
  name: 'username',
  label: 'Username',
  type: 'text',
  validations: [{type: 'required', message: 'Choose a username.'}]
}

If a required field is empty, the form is not submitted.

validations

validations is an optional DyonaFieldValidation[]:

validations?: DyonaFieldValidation[]

Each entry has these parameters:

{
  type: '...',
  value: ...,
  message: '...'
}

• type selects the rule.
• value provides the limit or pattern when the rule needs one.
• message is optional and replaces DYONA Form's default message for that rule.

Multiple rules can be declared together:

validations: [
  {type: 'minLength', value: 4},
  {type: 'maxLength', value: 24}
]

min

min is valid only for type: 'number'. It defines the lowest allowed numeric value, and value must be a finite number.

{
  name: 'employeeCount',
  label: 'Employees',
  type: 'number',
  validations: [
    {type: 'min', value: 1}
  ]
}

Values lower than the configured minimum produce a validation error.

max

max is valid only for type: 'number'. It defines the highest allowed numeric value, and value must be numeric.

{
  name: 'employeeCount',
  label: 'Employees',
  type: 'number',
  validations: [
    {type: 'max', value: 500}
  ]
}

Values higher than the configured maximum produce a validation error.

minLength

minLength defines the minimum number of characters. It is valid only for text, textarea, email, and password fields. Its value must be an integer greater than or equal to 0.

{type: 'minLength', value: 4}

maxLength

maxLength defines the maximum number of characters. It is valid only for text, textarea, email, and password fields, and its value must be an integer greater than or equal to 0.

{type: 'maxLength', value: 24}

regex

regex validates the value with a regular expression. It is valid only for text, textarea, email, and password fields. Its value must be a non-empty string representing a valid RegExp.

{
  name: 'username',
  label: 'Username',
  type: 'text',
  validations: [
    {type: 'regex', value: '^[a-z0-9.]+$'}
  ]
}

message

message?: string is an optional property of a declarative validation:

validations: [
  {
    type: 'minLength',
    value: 4,
    message: 'Username must contain at least 4 characters.'
  }
]

message is optional. When it contains valid text, it replaces the default message generated by DYONA Form for that rule. If it is empty or contains only whitespace, DYONA Form uses the default message. Its content belongs to the consuming application, which is responsible for localizing it.

Email validation

email is not a DyonaFieldValidationType. Email format validation happens automatically when a field uses type: 'email':

{
  name: 'email',
  label: 'Email',
  type: 'email',
  required: true
}

DYONA Form validates the email format when the field contains a value.

Password validation

passwordRules does not belong in the validations array. Configure it directly on a type: 'password' field:

passwordRules: {
  minLength?: number,
  requireUppercase?: boolean,
  requireLowercase?: boolean,
  requireNumber?: boolean,
  requireSymbol?: boolean
}

• minLength sets the minimum password length and must be a positive integer greater than 0.
• requireUppercase is a boolean and requires at least one uppercase letter when true.
• requireLowercase is a boolean and requires at least one lowercase letter when true.
• requireNumber is a boolean and requires at least one number when true.
• requireSymbol is a boolean and requires at least one symbol when true.

{
  name: 'password',
  label: 'Password',
  type: 'password',
  required: true,
  passwordRules: {
    minLength: 8,
    requireUppercase: true,
    requireLowercase: true,
    requireNumber: true,
    requireSymbol: true
  },
  showPasswordRules: true
}

showPasswordRules is a boolean. When it is true, it visually displays the configured password rules to the user.

Optional fields

When a field is not required and is empty, DYONA Form does not run its content validations. For example, an empty optional email is valid; if it contains a value, its email format is validated.

Error behavior

When a validation fails, DYONA Form displays the error below the field. The corresponding tab reflects its errors, and a navigable global error summary is available. When saving is attempted, DYONA Form navigates to and focuses the first invalid field.

Conditional required

requiredWhen makes a field required based on another field's value:

{
  name: 'taxId',
  label: 'Tax ID',
  type: 'text',
  requiredWhen: {
    field: 'accountType',
    operator: 'equals',
    value: 'business'
  }
}

Complete condition documentation is covered in its own section.

Complete example

import {DyonaForm, type DyonaFormSchema} from '@typhonsoftware/dyona-form';

const schema: DyonaFormSchema = {
  title: 'Create account',
  hideSingleTab: true,
  tabs: [{
    id: 'account',
    title: 'Account',
    rows: [
      {columns: [
        {
          name: 'username', label: 'Username', type: 'text', required: true,
          validations: [{type: 'minLength', value: 4}]
        },
        {name: 'email', label: 'Email', type: 'email', required: true}
      ]},
      {columns: [
        {
          name: 'password', label: 'Password', type: 'password', required: true,
          passwordRules: {
            minLength: 8, requireUppercase: true, requireLowercase: true,
            requireNumber: true, requireSymbol: true
          },
          showPasswordRules: true
        },
        {
          name: 'employeeCount', label: 'Employees', type: 'number',
          validations: [{type: 'min', value: 1}, {type: 'max', value: 500}]
        }
      ]}
    ]
  }]
};

export function AccountForm() {
  return <DyonaForm schema={schema} />;
}