hollodk / beastvalidator
A DOM-powered JS form validator with tooltips, inline messages, and beautiful UX
Installs: 19
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Language:JavaScript
pkg:composer/hollodk/beastvalidator
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
andmaxlength
- π Age range validation via
data-min-age
anddata-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