Collections

Declaring rules for collections

Your forms may often include validations for collections where you need to validate multiple items sharing a nested structure. This can be easily achieved using $each in the rules declaration.

You can also add validations for the field containing the array itself.

WARNING

Due to a JavaScript limitation with Primitives, it's recommended to use only arrays of objects.

Primitives (Strings, Numbers etc...) are immutable, so they can't be modified to add a tracking ID (which is how Regle works for collections).

const form = ref<{ collection: Array<{ name: string }> }>({
  collection: []
})

const { r$ } = useRegle(form, {
  collection: {
    $each: {
      name: { required },
    }
  }
})

Displaying collection errors

For collections, the best way to display errors is to bind your list to the $each linked to your state. In this example, r$.$fields.collection.$each.

Alternatively, you can map your errors using r$.$errors.collection.$each.

<template>
  <div 
    v-for="item of r$.$fields.collection.$each" 
    :key="item.$id">
    <div>
      <input
        v-model="item.$value.name"
        :class="{ valid: item.$fields.name.$valid }"
        placeholder="Type an item value"
      />

      <ul>
        <li v-for="error of item.$fields.name.$errors" :key="error">
          {{ error }}
        </li>
      </ul>
    </div>
  </div>

  <button type="button" @click="form.collection.push({ name: '' })">Add item</button>
  <button type="button" @click="r$.$resetAll">Reset</button>
</template>

<script setup lang="ts">
import { useRegle } from '@regle/core';

const form = ref<{ collection: Array<{ name: string }> }>({
  collection: [{ name: '' }],
});

const { r$ } = useRegle(form, {
  collection: {
    $each: {
      name: { required },
    },
  },
});
</script>

Result:

Validating the array independently

Sometimes, you may want to validate not only each field in every element of the array but also the array itself, such as its size.

You can do this just like you would with a normal field.

Errors can be displayed either using r$.$errors.[field].$self or r$.$fields.[field].$field.$errors.

import { useRegle } from '@regle/core';

const form = ref<{ collection: Array<{ name: string }> }>({
  collection: [{ name: '' }],
});

const { r$ } = useRegle(form, {
  collection: {
    minLength: minLength(4),
    $each: {
      name: { required },
    },
  },
});

Result:

Accessing the current item state

In each item of your collection, you may have a validation that depends on another property of the item. You can access the current item's state and index by providing a function callback to $each.

import { useRegle } from '@regle/core';

const form = ref({
  collection: [{ name: '', condition: false }],
});

const { r$ } = useRegle(form, {
  collection: {
    $each: (item, index) => ({
      name: { required: requiredIf(() => item.value.condition) },
    }),
  },
});

Result:

Required

Providing a custom key to track items

By default, Regle generates a random ID to track your items and maintain their state through mutations. This ID is stored in $id and can be used in Vue as a key for rendering.

You can also provide your own key to the rule for custom tracking:

import { useRegle } from '@regle/core';

const form = ref({
  collection: [{ name: '', uuid: '28xja83' }],
});

const { r$ } = useRegle(form, {
  collection: {
    $each: (item) => ({
      $key: item.value.uuid,
      name: { required },
    }),
  },
});