Form Validation on Hyva: Replacing Magento’s jQuery Validation With Hyva’s Advanced Form Validation

On Hyva, form validation starts with native HTML5 constraints and adds an Alpine.js library, Advanced Form Validation, for anything the browser cannot express. You load it with the hyva_form_validation layout handle, initialize it with hyva.formValidation($el), and declare rules in a JSON data-validate attribute. Luma’s jQuery rules must be mapped or rewritten.

That summary hides most of the migration work. Luma stores ship dozens of forms that rely on mage/validation rule names, custom $.validator.addMethod rules, and data-mage-init wiring that silently does nothing on Hyva. This guide explains how the Hyva library works, maps the common Luma rules to their Hyva equivalents, shows how to port custom and async rules, and lists the pitfalls that show up most in checkout and CMS forms.

How Luma validates forms

Luma uses jQuery Validate wrapped by Magento. Adobe’s custom form validation guide shows a form initialized with data-mage-init='{"validation":{}}' and four ways to attach rules to a field: a data-validate JSON attribute, a plain required attribute, a CSS class such as required-entry, or rules listed inside the data-mage-init configuration.

The rules themselves live in Magento’s mage/validation.js as a large rules object of method and message pairs, with names such as validate-email, validate-password, validate-zip-us, and validate-number. Custom rules are added through $.validator.addMethod, usually in a RequireJS mixin.

All of that depends on jQuery and RequireJS. Hyva removes both from the storefront, so none of it runs.

How Hyva validates forms

Hyva takes a two-layer approach.

Layer one is the browser. Hyva’s documentation says it uses mostly HTML5 input types and the browser’s constraint validation API. A field with type="email", required, minlength, or pattern is validated by the browser with no extra JavaScript, and screen readers already understand those attributes.

Layer two is Advanced Form Validation. For rules the browser cannot handle, such as matching a confirmation password, checking a phone format, or asking the server whether a username is free, Hyva provides an Alpine.js library. The Hyva JavaScript form validation documentation states it has been available since Hyva 1.1.14 and is designed to follow accessibility best practices.

To use the library on a page, add the layout handle in that page’s layout XML:

<update handle="hyva_form_validation"/>

Then initialize it on the form:

<form x-data="hyva.formValidation($el)" @submit="onSubmit">
    <div class="field field-reserved">
        <input name="email" type="email" data-validate='{"required": true, "email": true}' @change="onChange">
    </div>
</form>

If the form already has its own Alpine component, merge them: x-data="{...initMyForm(), ...hyva.formValidation($el)}". The library adds novalidate to the form so the browser’s default bubbles do not compete with its own messages.

Built-in rules

The Hyva documentation lists these rules out of the box:

• required, minlength, maxlength, pattern, min, max, and step, which use the browser constraint API. The pattern rule was added in Hyva 1.1.21 and 1.2.1.
• email, which uses Magento’s email regular expression.
• password, which uses Magento’s password regular expression.
• equalTo, which compares a field with another field, typically for password confirmation.

One version note matters for upgrades. According to the Hyva 1.1.20 upgrade notes, the password rule is no longer applied automatically to type="password" fields. You opt in with data-validate='{"password": true}'.

Mapping Luma rules to Hyva

There is no automatic translation. Each Luma rule name has to become a Hyva rule, an HTML attribute, or a custom rule.

A useful first step in any migration is to grep the theme and every installed module for data-mage-init validation, required-entry, and validate- class names. That list becomes the porting backlog.

Writing custom rules

Custom rules are registered with hyva.formValidation.addRule(). The Hyva documentation uses a phone number example:

hyva.formValidation.addRule('phone', function (value, options, field, context) {
    const phoneNumber = value.trim().replace(' ', '');
    if (phoneNumber.length !== 9) {
        return 'Enter correct phone number, like XXX XXX XXX';
    }
    return true;
});

A rule returns true when the value is valid, or a message string when it is not. It can also return an object with type: 'html' for richer messages. In a real template, the message should be translated with __() and escaped with $escaper->escapeJs().

Fields then use the rule by name: data-validate='{"phone": true}'.

Two details catch developers coming from Luma:

1. data-validate must be strict JSON. The library parses it with JSON.parse(). Single quotes inside the value, unquoted keys, or trailing commas break validation for that field.
2. Rule names are global. If two modules register a rule with the same name, the later one wins. Prefix custom rules with your vendor name.

Async rules: asking the server

Some checks need the server, such as whether an email already has an account or a promo code exists. Hyva supports this directly. A rule can return a Promise, and the library’s onSubmit handler blocks submission until every rule has resolved. The documentation’s example checks username availability with a POST request, disables the field while the request runs, and re-enables it when it completes.

Keep three rules in mind for async validation:

• Debounce it. Running a request on every keystroke adds load and can trigger rate limits.
• Always validate on the server as well. Client-side checks improve the experience; they are not a security control.
• Handle failure. If the request errors, decide whether the field should pass or fail, and show a message either way.

Messages, styling, and translation

The library lets you control both wording and markup:

• Override a rule’s message per field with data-msg-RULENAME, for example data-msg-required="Please enter your company name". A %0 placeholder is replaced with the rule’s argument.
• Configure wrapper and state classes when initializing. The defaults are field field-reserved for the field wrapper, messages for the message container, field-success for valid fields, and field-error for invalid ones.
• The field-reserved class reserves space for the error message, which prevents layout shift when an error appears. Keep it unless your design handles that space another way.

For custom submit handling, the documented pattern is to call validate(), submit on success, and focus the first invalid field on failure. Focusing the first error is a small detail that matters for keyboard and screen reader users.

Forms in CMS content

Merchandisers often build contact or lead forms in CMS pages and blocks, where layout XML is not available. Hyva documents a block directive for this case that loads the validation script from a CMS page:

{{block class="Magento\Framework\View\Element\Template" template="Hyva_Theme::page/js/advanced-form-validation.phtml"}}

Without it, the data-validate attributes in a CMS form do nothing.

Checkout and Magewire pitfalls

Hyva Checkout uses Magewire, and the interaction between Magewire and the validation library has a few specific traps. The Magewire form validation documentation covers them:

• novalidate can disappear. When Magewire re-renders a component, it removes the novalidate attribute unless the template includes it explicitly. Put it in the template.
• wire:submit.prevent skips validation. It conflicts with the library. The documented alternative is to call validate() first and then the Magewire submit method in its success branch.
• The validity flag must be an integer. data-magewire-is-valid expects 1 or 0, not true or false.

Hyva Checkout’s form API also lets PHP set validation rules on fields, which render as data-validate attributes, and the documentation warns: “Do not rely exclusively on client-side validation!”

Testing validation before launch

Validation bugs rarely show up in a quick click-through, because the happy path works. They show up when a shopper pastes a phone number with spaces, submits with the Enter key, or uses autofill. Build a short test matrix for each form:

• Empty submit. Every required field should show its own message, and focus should move to the first invalid field.
• Each rule in isolation. Enter a value that fails one rule at a time and confirm the message matches the rule, not a generic error.
• Autofill. Browser autofill does not always fire the events a component listens for. Confirm that autofilled fields still validate on submit.
• Keyboard only. Tab through the form, submit with Enter, and confirm that error messages are announced and reachable.
• Slow network. Throttle the connection and confirm async rules disable submission until they resolve, and that a failed request produces a clear message.
• Server rejection. Submit a value that passes client rules but fails on the server, and confirm the server error is shown in the same place as client errors.

Automating the first two checks in an end-to-end suite catches most regressions when a module or theme update changes a template. Keep the rest as a manual checklist for each release that touches forms.

A porting checklist

1. Inventory every form: account, checkout, contact, newsletter, product questions, B2B quote and company forms, and CMS forms.
2. Find all Luma validation wiring with a grep for data-mage-init, validate-, and required-entry.
3. Replace what the browser can handle with native attributes first.
4. Add the hyva_form_validation handle, or the CMS directive, wherever the library is needed.
5. Port each custom $.validator.addMethod rule to addRule() with a vendor-prefixed name.
6. Add {"password": true} where password strength rules are expected.
7. Confirm every rule is also enforced on the server.
8. Test each form with keyboard only and with a screen reader, and check that errors do not shift the layout.

Teams retraining from Knockout will recognize the same shift we describe in moving a Magento frontend team from Knockout to Alpine. Forms from third-party extensions follow the process in our guide to adapting Magento extensions to Hyva, and every form belongs on the acceptance list in a Hyva frontend cutover and rollback plan.

Working with Bemeir

Bemeir is a Brooklyn ecommerce agency. Our Hyva development services and Magento development services cover theme builds, checkout, and extension compatibility for Magento Open Source and Adobe Commerce. We also provide Shopify development, Shopware development, and BigCommerce development. Learn more about Bemeir, see our technology partners, or visit the Bemeir home page.

FAQ

Does Hyva use jQuery validation?

No. Hyva removes jQuery and RequireJS from the storefront, so Luma’s mage/validation rules do not run. Hyva relies on native HTML5 constraint validation and its own Alpine.js Advanced Form Validation library, available since Hyva 1.1.14.

How do I enable form validation on a Hyva page?

Add <update handle="hyva_form_validation"/> to the page’s layout XML, then initialize the form with x-data="hyva.formValidation($el)" and @submit="onSubmit". Declare rules on fields with a JSON data-validate attribute or native HTML attributes.

How do I add a custom validation rule in Hyva?

Register it with hyva.formValidation.addRule('name', function (value, options, field, context) {...}). Return true for a valid value or a message string for an invalid one, then reference the rule on a field with data-validate='{"name": true}'.

Can Hyva form validation call the server?

Yes. A rule can return a Promise, and the library waits for every rule to resolve before allowing submission. Use this for checks such as account or code availability, debounce the requests, and always repeat the check on the server.

Why does my Hyva checkout form submit without validating?

The most common cause is wire:submit.prevent, which conflicts with the validation library. Call validate() first and submit through Magewire in its success branch. Also check that novalidate is in the template, since Magewire removes it on re-render otherwise.