`) so the message lands next to it. - A group of radios or checkboxes that each sit in their own `` gets one message on the group's container. - The intl-tel-input wrapper (`.iti`) is skipped, so the message goes below the phone field. ### Custom placement Put an element with `data-submito-error=""` anywhere in the form, and submito writes into it instead: ```html

``` submito never removes your element. It only sets and clears its text, so you can style the empty state with `:empty`. ## Styling ```css .error-message { display: block; margin-top: 0.25rem; font-size: 0.875rem; color: #b00020; } [aria-invalid="true"] { border-color: #b00020; } .error > label, .error .label { color: #b00020; } form[aria-busy="true"] { cursor: progress; } ``` Error text is always set with `textContent`, never as HTML. ## Loading indicator ```html ``` ```js submito.newForm({ form: '#contact', indicator: '#sending' }); ``` See [Configuration → indicator](/configuration.md#indicator) for the class rules (`hidden`, `uk-hidden`, `d-none`). ## Multiple forms Call `newForm` once per form: ```js submito.newForm({ form: '#newsletter' }); submito.newForm({ form: '#contact', indicator: '#contact-sending' }); ``` Each instance is independent. Events are dispatched on their own form element, so listeners never need to filter by id unless they listen on `document`. ## Forms added later Call `newForm` after the form exists in the DOM, for example after you inject it or when your component mounts. When you remove it again, call `form.destroy()`. Calling `newForm` twice on the same form element replaces the old instance. --- # Validation submito validates in the browser before anything is sent. The rules come from the HTML you already write. Failed checks show inline messages, focus the first invalid field, fire [`submito:invalid`](/events.md), and skip the request. :::warning Not a security boundary Anyone can bypass browser checks or call your endpoint directly. Always validate again on the server. See [Security](/security.md). ::: ## Rules | HTML | Message key | Default message | |------|-------------|-----------------| | `required` (whitespace-only counts as empty) | `required` | This field is required. | | `type="email"` (also `multiple`) | `email` | Please enter a valid email address. | | `type="url"` | `url` | Please enter a valid URL. | | `type="number"` with non-numeric input | `number` | Please enter a valid number. | | `minlength="8"` | `minlength` | Please enter at least {min} characters. | | `maxlength="200"` | `maxlength` | Please enter no more than {max} characters. | | `min="18"` (numbers, dates) | `min` | Please enter a value of {min} or more. | | `max="120"` | `max` | Please enter a value of {max} or less. | | `step` mismatch, unparsable dates | `invalid` | Please enter a valid value. | | `pattern="…"` | `pattern`, or the field's `title` | Please match the requested format. | | intl-tel-input number | `phone` | Please enter a valid phone number. | | `name="numb_captcha"` | `captcha` | Incorrect answer. Please try again. | Checks run in that order. Only the first failing rule is shown. Disabled, readonly and hidden fields, and fields without a `name`, are skipped. ### Custom message per pattern The `title` attribute becomes the message for `pattern`: ```html ``` ### Change the wording Override any message for one form with `messages` (see [Internationalization](/internationalization.md)): ```js submito.newForm({ form: '#signup', messages: { required: 'Required', minlength: 'At least {min} characters, please.', }, }); ``` ### Custom rules with `setCustomValidity` Anything you set with the standard `setCustomValidity()` API is shown like a built-in rule: ```js const confirm = document.querySelector('[name="password_confirm"]'); confirm.addEventListener('input', () => { const same = confirm.value === document.querySelector('[name="password"]').value; confirm.setCustomValidity(same ? '' : 'Passwords do not match.'); }); ``` Attach the listener to the field itself. It then runs before submito's listener on the form, so submito sees the updated validity. ## When validation runs **On submit.** Every field is checked and the first invalid one is focused. **While the user works on the form** (`liveValidation: true`, the default): 1. Nothing is flagged while someone types into a field for the first time. 2. When they leave a field they changed (or pick an option, or toggle a checkbox), that field is checked. 3. After that, the field is re-checked on every keystroke. Errors disappear as soon as the value is fixed. 4. After a submit attempt, every field is re-checked on every keystroke. Tabbing through an empty field does not show an error. Resetting the form clears all messages and starts over. Set `liveValidation: false` to validate only on submit. ### Validate from code ```js const form = submito.newForm({ form: '#checkout' }); nextStepButton.addEventListener('click', () => { if (form.validate()) goToNextStep(); }); ``` `validate()` shows the messages, focuses the first invalid field, and returns `true` when everything passes. ## Server-side errors Messages returned by your API are shown next to the matching field in the same way. See [Server responses](/server-responses.md). They are cleared when the user edits the field, or on the next submit. --- # Server responses submito sends `multipart/form-data` (the form's `FormData`) with `Accept: application/json`. Your endpoint should return JSON. submito turns the reply into a single response object. ## The response object This is what `callback`, the events and `form.submit()` give you: ```js { success: true, // HTTP 2xx and the body does not signal an error status: 200, // HTTP status; 0 if no response arrived (network or captcha failure) message: 'Thanks!', // the server's message, '' when there is none errors: [ // normalized errors (see below) { name: 'email', message: 'Already registered.' }, { name: null, message: 'Try again tomorrow.' }, ], data: { /* the parsed JSON body, the raw text if it is not JSON, or null */ }, } ``` ## How success is decided A response is a **success** when the HTTP status is 2xx **and** the JSON body does not report an error. The body is checked in this order, and the first match wins: 1. `success: true | false` 2. `status`: `"success"`, `"ok"`, or a 2xx number means success. `"error"`, `"fail"`, `"failed"`, `"invalid"`, or a number ≥ 400 means error. 3. `code`: same rules as `status`. 4. A non-empty `error` string, or a non-empty `errors` value, means error. A body without any of these signals follows the HTTP status. Empty bodies and non-JSON bodies never throw: an HTML error page with HTTP 500 becomes `{ success: false, status: 500, data: '…' }`. ## Message The first non-empty string of `message`, `msg`, `error`, or `data.message` is used. For WordPress-style replies, `data` itself is used when it is a string. When the server sends no message, the built-in UI falls back to localized defaults ("Your submission has been received." / "We could not process your request."). ## Errors All of these shapes are accepted and normalized to `{ name, message }`: ```jsonc // Array of objects: name | field | path | param, and message | error | msg "errors": [{ "name": "email", "message": "Already registered." }] // Object keyed by field (Laravel, Rails, Django): first message per field "errors": { "email": ["The email has already been taken."] } // Plain strings: general errors "errors": ["Mail server unavailable."] ``` Field names are matched to `name` attributes. `tags` also matches `tags[]`, and dotted names like `user.email` match `user[email]`. Errors that match no field are shown in the popup instead. ## Recommended payloads ```json { "status": "success", "message": "Thanks, we will reply within a day." } ``` ```json { "status": "error", "message": "Please fix the highlighted fields.", "errors": [{ "name": "email", "message": "This email is already registered." }] } ``` Send field errors with HTTP 422 (or 400). With the built-in UI, field errors are shown inline and the first one is focused. A popup appears only when there is a `message` or an error that did not match a field. ## Express ```js import express from 'express'; import multer from 'multer'; const app = express(); const upload = multer(); // parses multipart/form-data app.post('/api/contact', upload.none(), (req, res) => { const { name, email } = req.body; if (!email) { return res.status(422).json({ status: 'error', message: 'Please fix the highlighted fields.', errors: [{ name: 'email', message: 'Email is required.' }], }); } // …save, send mail… res.json({ status: 'success', message: `Thanks, ${name}!` }); }); app.listen(3000); ``` Use `upload.single('attachment')` / `upload.array('files[]')` for file fields. ## PHP ```php 'error', 'message' => 'Please fix the highlighted fields.', 'errors' => [['name' => 'email', 'message' => 'Email is required.']], ]); exit; } // …save… echo json_encode(['status' => 'success', 'message' => 'Message sent!']); ``` Text fields are in `$_POST`, files in `$_FILES`. ## Laravel Laravel's validation replies work as they are: ```php public function store(Request $request) { $request->validate([ 'email' => ['required', 'email', 'unique:subscribers'], ]); // … return response()->json(['message' => 'Subscribed!']); } ``` A failed `validate()` returns HTTP 422 with `{ message, errors: { email: [...] } }`. submito shows each field error inline and the message in the popup. The `Accept: application/json` header that submito sends is what makes Laravel answer with JSON instead of a redirect. For CSRF, add the token to `headers` (see [Security](/security.md#csrf)). ## WordPress `wp_send_json_success()` / `wp_send_json_error()` replies are understood: ```php add_action('wp_ajax_nopriv_contact', 'my_contact'); add_action('wp_ajax_contact', 'my_contact'); function my_contact() { check_ajax_referer('contact'); if (empty($_POST['email'])) { wp_send_json_error([ 'message' => 'Please fix the highlighted fields.', 'errors' => ['email' => 'Email is required.'], ], 422); } wp_send_json_success(['message' => 'Thanks!']); } ``` ```js submito.newForm({ form: '#contact', url: '/wp-admin/admin-ajax.php', data: { action: 'contact', _ajax_nonce: window.contactNonce }, }); ``` --- # Response UI Unless you pass a `callback`, submito handles the response for you: | Response | What happens | |----------|--------------| | Success | Popup with the server message (or a default), then `form.reset()` | | Error with field errors | Messages next to the fields, first one focused. Popup only if there is also a message or an unmatched error | | Any other error | Popup with the message (network failures and non-JSON errors get a localized default) | `responseType` picks the popup: | `responseType` | Popup | |----------------|-------| | `'dialog'` (default) | Built-in native `