website·Indexed 32 days ago
https://reglejs.devA headless validation library for Vue 3.4+, designed to replace repetitive validation logic. Regle features a composable-based API via `useRegle`, support for reusable and built-in rules, async validation, and integration with Nuxt and Standard Schema libraries like Zod and Valibot. It includes specialized tools for handling discriminated unions, scoped validation, and a dedicated Devtools suite for debugging validation trees.
r$ object) provides a set of computed properties and methods to track the validation state of specific rules. These properties allow developers to programmatically check if a specific rule (like required) is valid, pending, or active, and to retrieve its associated error messages or metadata.<script setup lang='ts'>
import { useRegle } from '@regle/core';
import { required } from '@regle/rules';
import { ref } from 'vue';
const form = ref({ email: '', user: { firstName: '', lastName: '' } });
const { r$ } = useRegle(form, {
email: { required },
user: {
firstName: { required },
}
})
// Accessing properties of the 'required' rule for the 'email' field
console.log(r$.email.$rules.required.$valid);
</script>useRegle is the core composable of Regle that transforms form data and validation rules into a reactive validation system. It requires the Vue Composition API to function. It takes three parameters: the state (data), the validation rules, and optional modifiers.<script setup lang='ts'>
import { useRegle } from '@regle/core';
const { r$ } = useRegle(
/* 1. Your data (state) */,
/* 2. Your validation rules */,
/* 3. Optional modifiers */
);
// r$ contains validation state, errors, and methods
</script>createVariant for nested values, the first argument must be a reactive getter function to ensure Regle can track the nested state changes.const state = ref({
firstName: '',
login: { type: '', email: '' }
});
const { r$ } = useRegle(state, () => {
// Use getter syntax () => state.value.login for nested variants
const loginVariant = createVariant(() => state.value.login, 'type', [
{ type: { literal: literal('EMAIL') }, email: { required, email } },
{ type: { literal: literal('GITHUB') }, username: { required } },
{ type: { required } },
]);
return {
firstName: { required },
login: loginVariant.value
};
});r$.field.$errors, or globally via r$.$errors.field or r$.$silentErrors.field.<template>
<input
v-model='r$.$value.email'
:class="{ error: r$.email.$error }"
placeholder='Type your email'
/>
<li v-for="error of r$.email.$errors" :key='error'>
{{ error }}
</li>
</template>
<script setup lang='ts'>
import { useRegle } from '@regle/core';
import { required, minLength, email } from '@regle/rules';
const { r$ } = useRegle({ email: '' }, {
email: { required, email, minLength: minLength(4)}
})
</script>r$.$validate() to trigger validation for the entire form. This returns an object containing a valid boolean and the validated data.async function handleSubmit() {
const { valid, data } = await r$.$validate()
if (!valid) {
console.log('Form has errors')
return
}
try {
await submitForm(data)
r$.$reset() // Reset form after success
} catch (error) {
// Handle submission error
}
}
createRule utility from @regle/core to define reusable, type-safe validation rules. This utility simplifies the definition of a rule's type, parameters, active state, and automatic tracking of reactive dependencies.import { createRule } from '@regle/core';
import { isFilled } from '@regle/rules';
export const required = createRule({
validator: (value: unknown) => {
return isFilled(value);
},
message: 'This field is required',
});Replace the core useRegle composable with useRegleSchema from @regle/schemas to integrate Standard Schema compliant libraries. Regle supports Zod (3.24+), Valibot (1+), and ArkType (2+).
Limitations compared to core rules:
$validate and $pending are only available at the root level.$rules (e.g., xx.$rules.required.active) is not available.import { useRegleSchema } from '@regle/schemas';
import { z } from 'zod'; // Or valibot / arktype
// Example with Zod
const { r$ } = useRegleSchema({ name: '' }, z.object({
name: z.string().min(1)
}));@regle/rules package. This package must be installed separately from the core library.# Using pnpm
pnpm add @regle/rules
# Using npm
npm install @regle/rules
# Using yarn
yarn add @regle/rules
# Using bun
bun add @regle/rulesRegle automatically detects parameters in the validator function and transforms the rule into a function declaration. These parameters can be plain values, Vue refs, or getter functions, and they are registered as reactive dependencies.
Important Reactivity Note: If passing a raw value as a parameter, the rule will only be reactive if the entire rules object is declared as a computed property or a getter function within useRegle.
import { createRule, type Maybe } from '@regle/core';
export const myValidator = createRule({
validator: (value: Maybe<string>, arg: number) => {
return true;
},
message: ({ $params: [arg] }) => {
return `Invalid value based on ${arg}`;
}
});
// Usage in useRegle
const max = ref(5);
useRegle({name: ''}, {
name: {
rule1: myValidator(5), // Plain value
rule2: myValidator(max), // Ref
rule3: myValidator(() => max.value) // Getter
}
})