README

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)

Add your form

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

Initialize BeastValidator

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

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/dist/validate.umd.js"></script>
<link rel="stylesheet" href="/your-path/dist/style.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

Option	Type	Default	Description
`errorContainerClass`	string	`'beast-error-msg'`	Class name for inline errors
`tooltipClass`	string	`'beast-tooltip'`	Class name for tooltips
`focusFirst`	bool	`true`	Scroll/focus first invalid field
`validateOnChange`	bool	`true`	Validate on `input` and `change` events
`tooltips`	string	`'none'`	Tooltip position (`top-left`, `top-right`, `top-center`)
`helperText`	bool	`true`	Show inline error below fields
`shakeInput`	bool	`true`	Shake animation for invalid fields
`waitForDom`	bool	`true`	Delay init until DOM is ready
`setNoValidate`	bool	`true`	Disable native browser validation
`autoSubmit`	bool	`true`	Auto submit form if valid
`initSteps`	bool	`false`	Enable step/wizard mode
`debug`	bool	`false`	Enable console logging
`language`	string	`'en'`	Language key from `messages`
`theme`	string	`'beast'`	`beast`, `bootstrap`, or `none`
`errorSummaryTarget`	string	`null`	CSS selector for error summary
`onInit`	func	`null`	Callback after init
`onFail`	func	`null`	Callback with invalid fields
`onSuccess`	func	`null`	Callback on valid form
`submitTo`	object	`null`	Automatically submit to an API endpoint { url, method, headers, debug }

📌 Supported `data-*` Attributes

Attribute	Example	Description
`data-min`	`2`	Min checkboxes or min value
`data-max`	`6`	Max numeric value
`data-min-age`	`18`	Minimum age in years
`data-max-age`	`100`	Maximum age in years
`data-password-strength`	`strong`	Enforce password complexity (`weak`, `medium`, `strong`)
`data-sleep`	`1.5`	Delay in seconds
`data-match`	`password`	Match field name
`data-validator`	`checkUsername`	Custom validator name
`data-error-message`	`Field required`	Override default message
`data-error-container`	`#myErrorBox`	Place error message in custom container

📌 Supported Attributes

Attribute	Example	Description
`pattern`	`[A-Z]{2}`	Custom regex format
`minlength`	`6`	Min charaters in form
`maxlength`	`2`	Max characters in form

🎨 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

File	Format	Use Case
`dist/validate.esm.js`	ESM	✅ Modern bundlers like Vite, Webpack, Rollup, etc.
`dist/validate.umd.js`	UMD	✅ For inclusion via `<script>` in a browser (dev mode)
`dist/validate.min.js`	UMD (minified)	✅ Production-ready browser version or CDN like jsDelivr

🧠 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

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

🤝 Contributing

We love contributions!

Fork the repo
Create a new branch
Write clean vanilla JS
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

hollodk / beastvalidator

Maintainers

Details