Rule Creation

Use and extend any built-in rule or define your own — asynchronous rules, cross-field rules, or even required-type rules that determine whether a field must be filled.

📝 Defining Rules

The defineRule() API requires a name string that is used to delcare the rules within the field. It also requires a validate() function that holds the validation logic. When not using a locale source, a default message must be supplied via message.

defineRule('minlength', {
  validate: (value, [limit]) => {
    return value.length >= limit
  },
  message: 'The {field} must be at least {limit} characters long.'
})

📝 Declaring Rules

Delcare the rule name as HTML attributes, then use it to write your own logic. The validate() function gives you access to the field’s value, params, and context.

<form>
  <input type="text" name="username" value="jim" />
  <input type="text" name="age" between="18,50" value="25" />
</form>

The validate() function for between accepts:

• value → 25
• params → [18,50]
• context:

{
  "field": "username",
  "type": "text",
  "attrValue": "18,50",
  "form": {
    "username": "jim",
    "age": "25"
  }
}

⚡ Built-in Rules

The Rules offers 50+ built-in validation rules — including files, dates, multi-selects, conditional requirements, and full support for all native browser rules. Import each rule individually, import by group, or import all at once (not recommended).

import { defineRule } from 'suriform'
import { min, max } from 'suriform/rules'

defineRule('min', min)
defineRule('max', max)

Each built-in rule are designed to be extended using object spreading. Override the message, change the format, or extend the validator however you want.

import { defineRule } from 'suriform'
import { min } from 'suriform/rules'

defineRule('min', {
  ...min,
  message: 'Value must be greater than or equal to {min}.'
})

🔄 Asynchronous

Return a simple boolean result to trigger the rule’s default message or chain multiple conditions with nested messages to have a more dynamic messaging.

defineRule('username', {
  validate: async (value) => {
    const res = await fetch(`/api/check-username?u=${value}`)
    const data = await res.json()
    return data.available
  },
  message: 'The {field} is already taken.'
})

💡 Learn more about message resolving with the Messaging guide.

↔️ Cross-Field

Using the checksTarget flag, the validate() function will have access to the FormData within the context object. This allows for easy access to the target field’s value.

defineRule('match', {
  validate: (value, [target], { form }) => {
    return value == form[target]
  },
  checksTarget: true,
  message: 'Fields do not match.'
})

<form>
  <input type="text" name="foo" match="bar" />
  <input type="text" name="bar" />
</form>

💡 Combine cross-field logic with async rules for complex validation scenarios.

✅ Required-Type

With the checksRequired flag, the system registers the rule in a different registry that runs an additional isFieldRequired() check, dedicated to required-type rules.

defineRule('required-with', {
  validate: (_, [target], { form }) => {
    if (!target) return false
    return !!form[target]
  },
  checksTarget: true,
  checksRequired: true
})

<form>
  <input type="text" name="foo" required-with="bar" />
  <input type="text" name="bar" />
</form>

💡 Learn more about validation flow with the validateForm() API.