🐾 BeastValidator

A flexible, no-dependency JavaScript form validator built for modern forms with great UX.

🔗 Live Demo 📁 GitHub Repository

BeastValidator is built for developers who want clean, dependency-free form validation with a great user experience. Unlike bulky frameworks or config-heavy libraries, BeastValidator works directly with native HTML5 attributes and gives you full control — perfect for landing pages, modals, or dynamic UIs.

✨ Features

• ✅ Validates required inputs, selects, checkboxes, radios
• 📧 Built-in email format validation
• 🔤 Pattern matching via pattern
• 📏 Min/max numeric range support via data-min / data-max
• 💡 Min/Max length validation via minlength and maxlength
• 🎂 Age range validation via data-min-age and data-max-age
• 🤝 Match another field with data-match
• 🔐 Password strength enforcement via data-password-strength="weak|medium|strong"
• 🔁 Real-time validation (input/change)
• 🫨 Shake animation for invalid fields
• ⬇️ Scrolls to and focuses first invalid field
• 📡 Optional API submission via submitTo
• 🧩 onFail, onSuccess, onInit callbacks
• 🧩 onSuccess(json) gives you a clean JSON object of all form values based on name=""
• 💬 Tooltip support in multiple positions
• 🌍 Multilingual error messages (EN, DA, DE, Pirate)
• ⏳ Delayed validation with data-sleep
• 🧪 Async field validation
• 🧩 Step wizard support (initSteps, data-step, nextStep, prevStep)
• ⌨️ Enter key triggers step validation and navigation automatically
• 🔄 data-next buttons automatically show "Validating..." and become disabled during step validation or Enter key press
• 🧠 Custom validators via data-validator
• 🧩 Error summary with clickable links
• 🔄 Reset method to clear all dirty states and visuals
• ⚙️ Auto-submit toggle
• 🧱 Theme support: beast, bootstrap, none
• 📦 Zero dependencies

🚦 Quick Start (in 3 steps)

1. Add your form

   <form id="myForm">
   <input name="email" type="email" required>
   <button>Submit</button>
   </form>
   

2. Initialize BeastValidator

   new BeastValidator('myForm', {
   onSuccess: (json) => console.log(json)
   });
   

3. Enjoy automatic validation!

🚀 Installation

✅ CDN

<script src="https://cdn.jsdelivr.net/npm/beastvalidator/dist/validate.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/beastvalidator/dist/style.min.css">

📦 NPM

npm install beastvalidator

import BeastValidator from 'beastvalidator';

🔗 NPM Package

🐘 Composer (PHP Projects)

composer require hollodk/beastvalidator

🔗 Packagist Package

🧾 Manual Download

git clone https://github.com/hollodk/beast-validator.git

<script src="/your-path/beast-validator.js"></script>
<link rel="stylesheet" href="/your-path/beast-validator.css">

📦 Module Mapping (for bundlers and CDNs)

If you're using a bundler, import BeastValidator from 'beastvalidator' will automatically resolve to the correct ESM build thanks to these fields in package.json:

{
  "main": "dist/validate.umd.js",
  "module": "dist/validate.esm.js",
  "unpkg": "dist/validate.min.js",
  "jsdelivr": "dist/validate.min.js"
}

🧪 Example Usage

✅ HTML Form

<form id="myForm">
  <input type="email" name="email" required>
  <input type="password" name="password" minlength="6" maxlength="20" required>
  <input type="password" name="confirm" data-match="password" required>
  <input type="text" name="code" pattern="^[A-Z]{2}$" required>
  <input type="number" name="guests" data-min="1" data-max="5" required>
  <input type="date" name="birthdate" data-min-age="18" data-max-age="99" required>
  <button type="submit">Submit</button>
</form>

✅ JavaScript Initialization

new BeastValidator('myForm', {
  tooltips: 'top-center',
  autoSubmit: false,
  debug: true,
  initSteps: false,
  onFail: (fields) => console.warn('Invalid fields:', fields),
  onSuccess: (data) => alert('Form successful'),
});

🧭 Step Wizard

Enable multi-step flow with initSteps: true. Sections are shown via data-step.

Add [data-next] and [data-prev] buttons to control flow. Enable with initSteps: true.

Wrap form sections with data-step="1", data-step="2", etc. Use:

HTML

<section data-step="1">
  <p>Step 1</p>
  <input type="email" name="email" required>
  <button type="button" data-next>Next</button>
</section>
<section data-step="2" data-validate="all">
  <p>Step 2</p>
  <input type="text" name="name" required>
  <button type="button" data-prev>Back</button>
  <button type="button" data-next>Submit</button>
</section>
<section data-step="3">
  <p>Step 3 / Thank you</p>
</section>

JavaScript

validator.nextStep();
validator.prevStep();

📡 API Submission (Optional)

You can use submitTo to automatically post the validated form data to an API endpoint, without writing your own fetch logic.

new BeastValidator('myForm', {
  submitTo: {
    url: 'https://api.example.com/form',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    onResponse(response) {
      console.log('[onResponse]', response);
      alert('🎉 Submission successful!');
      // You can redirect or update the UI here
    },
    onError(error) {
      console.warn('[onError]', error);
      alert('❌ Something went wrong. Please try again.');
      // You can re-enable a button or show server-side messages
    },
  },
});

⚙️ Options

📌 Supported data-* Attributes

📌 Supported Attributes

🎨 Styling

Add your own styles or override defaults:

.beast-tooltip {
  background: #f44336;
  color: #fff;
  padding: 5px 10px;
  border-radius: 4px;
}
.beast-error-msg {
  color: red;
  font-size: 0.85em;
}
@keyframes shake {
  0%, 100% { transform: translateX(0); }
  25% { transform: translateX(-4px); }
  75% { transform: translateX(4px); }
}
.shake { animation: shake 0.3s ease-in-out; }

📚 Public API

const validator = new BeastValidator('form');

// Validate the whole form
validator.validate();

// Validate a single field
validator.validateField(document.querySelector('[name="email"]'));

// Control step wizard
validator.nextStep();
validator.prevStep();

// Reset form
validator.reset();

// Extend language support
setMessages(lang, messages)

✨ Custom Field Validator Example

<input name="username" data-validator="checkUsername">

validator.addValidator('checkUsername', async (field) => {
  const value = field.value.trim();
  if (value === 'admin') return 'Username taken';
  return true;
});

🌐 Custom Language Messages

validator.setMessages('fr', {
  required: 'Ce champ est requis',
  email: 'Adresse e-mail invalide'
});
validator.setLanguage('fr');

🧩 Build Variants Overview

🧠 When to Use Which

1. 🛠 Vite/Webpack/Rollup (Modern JavaScript Apps)

Use: dist/validate.esm.js

Why: This is an ES module (ESM) file optimized for modern JavaScript tooling. It supports tree-shaking and integrates cleanly into apps built with frameworks like React, Vue, Svelte, or Alpine.

import BeastValidator from './dist/validate.esm.js';

const validator = new BeastValidator('formId', { ... });

• ✅ Works out-of-the-box with Vite, Webpack, Rollup, etc.
• ✅ Enables better build optimization (tree-shaking, minification)
• ✅ Recommended for app development

2. 🌐 Browser via <script> (Vanilla Sites or CMS like WordPress)

Use: dist/validate.min.js

Why: This is a minified UMD build that exposes BeastValidator globally via window.BeastValidator. Ideal if you're using BeastValidator directly in a browser without any build step.

<link rel="stylesheet" href="style.min.css">
<script src="dist/validate.min.js"></script>
<script>
  const validator = new BeastValidator('myForm', { debug: true });
</script>

• ✅ No build step needed
• ✅ Ready for use in HTML pages, WordPress, Laravel Blade, etc.
• ✅ Optimized for production (small size, fast load)
• ✅ Compatible with CDN usage (jsDelivr, unpkg)

3. 🤓 For Debugging in Browser Without Build Tools

Use: dist/validate.umd.js

Why: This is the non-minified UMD build, useful for debugging or exploring how BeastValidator works in browser developer tools.

<script src="dist/validate.umd.js"></script>
<script>
  const validator = new BeastValidator('myForm', { debug: true });
</script>

• ✅ Easier to read and debug in the browser
• 🚫 Not optimized for production (larger file size)

❓ FAQ

How do I validate only part of the form?

Use validateField() or validateCurrentStep().

Can I skip auto-submission?

Yes! Set autoSubmit: false and handle submission in onSuccess().

Does it work in React/Vue?

Yes, if you attach BeastValidator to a raw DOM node using ref.

Can I use it in modals or dynamic content?

Yes. Make sure to call new BeastValidator() after the form appears in the DOM.

Can I use BeastValidator without defining validation in JavaScript?

Yes! One of BeastValidator’s core strengths is that it leverages native HTML5 attributes like required, pattern, minlength, maxlength, type=email, and custom data-* attributes for validation logic. You don’t need to define a separate JS config.

Can I delay validation (e.g., to simulate an async check)?

Yes. Use the data-sleep="1" attribute to pause validation for X seconds before checking the value. Useful for async debouncing.

How can I debug what’s happening?

Set debug: true to get verbose console logging of all key lifecycle events:

new BeastValidator('myForm', { debug: true });

✅ Roadmap

• [x] Custom tooltips
• [x] Step-by-step wizard
• [x] Pattern and length validation
• [x] Custom error containers and messages
• [x] Multilingual support
• [x] Shake animation
• [x] Error summary rendering
• [x] Build files in dist
• [x] Build minified version
• [x] Age filter
• [x] Password strength validator
• [ ] TypeScript types
• [ ] Accessibility improvements

🤝 Contributing

We love contributions!

1. Fork the repo
2. Create a new branch
3. Write clean vanilla JS
4. Submit a PR 🚀

git clone https://github.com/hollodk/beast-validator.git

🌍 Browser Support

• ✅ Chrome, Firefox, Safari, Edge, Opera

📄 License

MIT — Free for personal & commercial use

👨‍💻 Author

Made with 💛 by @hollodk 🔗 Demo 📁 Repository