FORM VALIDATION ENGINE — INSTRUCTIONS
1. ADD THE ELEMENT

Install the plugin and place the Form Validation Engine element anywhere on the page.

The element is an invisible form controller. Its size and position do not affect the page layout.

2. ENABLE ID ATTRIBUTES

In the Bubble editor, go to:

Settings → General → Expose the option to add an ID attribute to HTML elements

3. ASSIGN UNIQUE ID ATTRIBUTES

Assign a unique ID Attribute to every field that must be validated.

Examples:

Full Name Input: full_name
Email Input: email
CPF Input: cpf
Password Input: password
Terms Checkbox: accept_terms

ID Attributes are case-sensitive and must be unique on the page.

4. CONFIGURE FIELD RULES

Enter one field per line in the Field Rules property.

Syntax:

field_id|required|validation_rule|rule:parameter|message:Custom error message

Example:

email|required|email|message:Please enter a valid email address.

Do not add bullets, numbering or HTML formatting. Use plain text with one field per line.

COMPLETE EXAMPLE

full_name|required|min:3|max:100|message:Please enter a valid full name.
email|required|email|message:Please enter a valid email address.
phone|required|phone_br|message:Please enter a valid Brazilian phone number.
age|required|number|message:Please enter a valid age.
numeric_code|required|numbers|message:Only numbers are allowed in the verification code.
birth_date|required|date|message:Please select a valid birth date.
cpf|required|cpf|message:Please enter a valid CPF number.
cnpj|required|cnpj|message:Please enter a valid numeric or alphanumeric CNPJ number.
cpf_cnpj|required|cpf_cnpj|message:Please enter a valid CPF or CNPJ number.
cep|required|cep|message:Please enter a valid Brazilian ZIP code.
rg|required|rg|min:5|max:14|message:Please enter a valid RG number.
website|required|url|message:Please enter a valid website URL.
country|required|message:Please select a country.
biography|required|min:20|max:300|message:The biography must contain between 20 and 300 characters.
password|required|strong_password|message:Use at least 8 characters with uppercase, lowercase, number, and special character.
confirm_password|required|confirm:password|message:The passwords do not match.
exact_code|required|digits_exact:6|message:The verification code must contain exactly 6 digits.
letters_only|required|letters|message:This field may contain letters and spaces only.
alphanumeric_code|required|alphanumeric|message:This field may contain letters and numbers only.
exact_username|required|exact:8|message:The username must contain exactly 8 characters.
cardholder_name|required|min:3|max:100|message:Please enter the cardholder name.
card_number|required|card|message:Please enter a valid card number.
accept_terms|required|message:You must accept the terms and conditions.

AVAILABLE RULES

required

Requires a value. A checkbox must be checked.

Example:

full_name|required

email

Validates an email address.

Example:

email|required|email

phone

Validates a generic international phone number containing between 8 and 15 digits.

Example:

phone|required|phone

phone_br

Validates a Brazilian landline or mobile phone number and applies an automatic mask.

Supported examples:

(21) 3333-4444
(21) 97555-0841
+55 (21) 97555-0841

Example:

phone|required|phone_br

number

Requires a value that can be interpreted as a number.

Example:

age|required|number

numbers

Allows digits only.

Example:

numeric_code|required|numbers

min

Defines the minimum number of characters.

Example:

full_name|required|min:3

max

Defines the maximum number of characters.

Example:

biography|required|max:300

exact

Requires an exact number of characters.

Example:

username|required|exact:8

digits_min

Requires a minimum number of digits. Formatting characters are ignored.

Example:

phone|required|digits_min:10

digits_max

Allows a maximum number of digits. Formatting characters are ignored.

Example:

phone|required|digits_max:11

digits_exact

Requires an exact number of digits. Formatting characters are ignored.

Example:

verification_code|required|digits_exact:6

url

Validates a URL or domain.

Example:

website|required|url

date

Applies a DD/MM/YYYY mask to Text inputs and validates a real calendar date.

Accepted validation formats:

DD/MM/YYYY
YYYY-MM-DD

Impossible dates such as 31/02/2020 are rejected.

Example:

birth_date|required|date

strong_password

Requires at least eight characters containing:

• One uppercase letter
• One lowercase letter
• One number
• One special character

Example:

password|required|strong_password

confirm

Compares the current field with another field using the other field’s ID Attribute.

Example:

confirm_password|required|confirm:password

same_as

Alternative rule for comparing two field values.

Example:

confirm_email|required|same_as:email

cpf

Applies a CPF mask and validates all eleven digits, including the two official check digits.

Example:

cpf|required|cpf

cnpj

Applies a CNPJ mask and validates the check digits.

This rule supports:

• Traditional numeric CNPJ
• Alphanumeric CNPJ
• Formatted or unformatted values

Example:

cnpj|required|cnpj

cpf_cnpj

Accepts either a valid CPF or a valid numeric/alphanumeric CNPJ and applies the corresponding mask.

Example:

document|required|cpf_cnpj

cep

Applies the 00000-000 mask and requires eight valid numeric positions.

This rule validates the format only. It does not check whether the address exists and does not call ViaCEP.

Example:

cep|required|cep

rg

Applies a common Brazilian RG mask and accepts a final X when applicable.

RG formats vary by state, so this rule performs structural validation instead of government identity verification.

Example:

rg|required|rg|min:5|max:14

letters

Allows letters, spaces, accents, apostrophes and hyphens.

Example:

full_name|required|letters

alphanumeric

Allows letters and numbers only.

Example:

reference_code|required|alphanumeric

card

Applies automatic number grouping and validates credit card numbers containing between 13 and 19 digits using the Luhn algorithm.

The rule does not verify whether the card exists, is active or can be charged.

Example:

card_number|required|card

message

Defines the custom error message returned when any validation rule for that field fails.

Example:

email|required|email|message:Please enter a valid email address.

INPUT CONFIGURATION

Use Content format: Text for fields that receive automatic masks:

• CPF
• CNPJ
• CPF or CNPJ
• CEP
• RG
• Brazilian phone
• Date
• Credit card

Do not use Integer format for masked fields because punctuation and alphanumeric CNPJ characters must be accepted.

FEEDBACK CONFIGURATION

Feedback Style supports:

Toast

Displays a non-blocking message in the page corner.

Modal

Displays centered feedback with an overlay.

None

Disables automatic feedback. Use this option when displaying your own Bubble popup or notification.

MESSAGE DURATION

Durations use milliseconds.

3000 = 3 seconds
5000 = 5 seconds
10000 = 10 seconds
0 = Remains open until manually closed

ELEMENT ACTIONS

Validate Form

Validates every visible field configured in Field Rules.

Recommended workflow:

When Validate Form button is clicked
→ Element Actions
→ Form Validation Engine
→ Validate Form

Reset Validation

Closes the active message, removes invalid field highlights and listeners, and resets all validation states.

Reset Validation does not erase values from Bubble inputs. Use Bubble’s own input reset functionality if the form values must also be cleared.

Close Message

Immediately closes the active Toast or Modal.

The Message closed event is triggered when an open message is successfully closed.

EXPOSED STATES

Form is valid — Yes/No

Returns yes when every processed field is valid.

Is validating — Yes/No

Returns yes while validation is running.

Total fields count — Number

Total number of processed fields.

Valid fields count — Number

Number of valid fields.

Invalid fields count — Number

Number of invalid fields.

Validation progress — Number

Returns a value from 0 to 100.

Display example:

Form Validation Engine’s Validation progress:rounded to 0

Add the % symbol as normal text outside the dynamic expression. Do not use Bubble’s percentage formatter.

First error message — Text

The first validation error message.

First invalid field ID — Text

The ID Attribute of the first invalid field.

Error messages — List of texts

A list containing every validation error message.

Invalid field IDs — List of texts

A list containing every invalid field ID.

Last validation result — Text

Possible values:

not_validated
valid
invalid
reset

EVENTS

Validation started

Triggered when validation begins.

Validation completed

Triggered when validation finishes, regardless of the result.

Validation succeeded

Triggered when every processed field is valid.

Use this event to save data, continue registration, submit an order or navigate to another page.

Validation failed

Triggered when at least one processed field is invalid.

Message opened

Triggered when a Toast or Modal is displayed.

Message closed

Triggered when an active feedback message is closed.

RECOMMENDED WORKFLOWS

Validate button:

When Validate Form button is clicked
→ Form Validation Engine → Validate Form

Successful validation:

When Form Validation Engine’s Validation succeeded event is triggered
→ Continue the submission or database workflow

Reset button:

When Reset Validation button is clicked
→ Form Validation Engine → Reset Validation

Close button:

When Close Message button is clicked
→ Form Validation Engine → Close Message

CUSTOM LANGUAGES

The default messages are in English, but custom field messages can be written in any language.

Portuguese example:

email|required|email|message:Digite um endereço de e-mail válido.
cpf|required|cpf|message:Digite um CPF válido.
accept_terms|required|message:Você precisa aceitar os termos.

HIDDEN FIELDS

When Validate hidden fields is disabled, fields inside hidden groups, collapsed containers or closed popups are ignored.

When enabled, configured hidden fields are also processed when they can be located on the page.

IMPORTANT NOTES

• Use one rule line per field.
• Do not duplicate ID Attributes.
• Keep the plugin element and fields on the same page.
• Fields created later inside popups must exist when validation runs.
• Client-side validation does not replace Bubble Privacy Rules.
• CPF and CNPJ validation checks mathematical check digits but does not confirm identity or registration status.
• CEP validation does not perform an address lookup.
• Credit card validation does not process payments.
• Automatic masks change the displayed input value but do not send it anywhere.
• Use Bubble workflows to store or normalize values when needed.

PRIVACY

All processing occurs locally in the browser.

No external API, account or API key is required. The plugin does not collect, store, transmit or track form values.

SUPPORT

Developed by Rincão Informática Academy.

For bug reports or feature suggestions, use the support contact available on the Bubble Marketplace plugin page.