{"slug":"validation-errors","meta":{"title":"Validation Errors","slug":"validation-errors","kind":"pattern","summary":"Tell someone a value is wrong next to that value, at the moment it can be fixed, in words that say what to do — and never take away what they typed.","problem":"A form is submitted and comes back with a red banner at the top, half the fields cleared, and a message naming a database constraint. The person now has to find which field, work out what was wrong with it, and retype the work the page discarded.","family":["capture","edit","recover"],"data_shape":["record"],"principles":["minimize-distance","orientation","friction"],"interaction":["feedback","editing"],"density":"low","complexity":"medium","status":"stable","visibility":"public","use_when":["Any form where a value can be rejected.","Rules exist that the person cannot see — uniqueness, formats, limits, relationships."],"avoid_when":["Never. The only question is whether the rule should exist, not whether to explain it."],"alternatives":[{"slug":"minimal-form","when":"The real fix is fewer fields, so there is less to get wrong."},{"slug":"smart-defaults","when":"The value could be supplied rather than demanded and then rejected."}],"ask_leo":"Fix the validation on this form.\n\n- Show each error directly beneath the field it belongs to, and mark that\n  field. A banner at the top is a summary, never the only message.\n- NEVER clear a field because validation failed. Keep everything the person\n  typed, exactly as typed.\n- Validate a field when it loses focus, so problems are found while the person\n  is still thinking about that field — not all at once at the end.\n- Once a field has an error, re-check it as they type so the error clears the\n  moment it is fixed.\n- Write each message as what happened, why, and what to do. Name the specific\n  rule and the specific offending value.\n- Never state a limit only in the error. If there is a maximum, say so before\n  they hit it.\n- On submit with several errors, move focus to the first one and, if it is off\n  screen, scroll it into view.\n- Do not use colour alone. An error carries a message and a marker as well as\n  a red border.\n- Never block submission on a rule the person cannot satisfy from this screen.\n  Explain and offer a route instead.\n","related":[{"title":"Words and Labels","url":"/patterns/words-and-labels","summary":"The writing rules that decide whether an error is useful at all."},{"title":"Async Actions Need Feedback","url":"/cookbook/async-action-feedback","summary":"The implementation side — never leave a submit in an unknown state."}]},"body":"## Anatomy\n\n```\n  Purchase order\n  ┌────────────────────────────┐\n  │ PO-2291                    │  ← what they typed is STILL THERE\n  └────────────────────────────┘\n  ⚠ PO-2291 is already used by INV-1039.\n    Use a different reference, or open INV-1039.\n       ↑ what happened · why · what to do — and a route\n```\n\n- **Beside the field.** The distance between the message and the thing it is\n  about is the cost of fixing it.\n- **The value survives.** Clearing a field on error is the single most\n  frustrating behaviour in forms, and it is a default in several frameworks.\n- **On blur, then live.** Check when they leave the field; once it is wrong,\n  re-check as they type so it clears itself.\n- **A route out**, when the rule involves something else.\n\n## Why it works\n\nValidation is a conversation about rules the person cannot see. The whole design\nquestion is how quickly and specifically the software explains a rule it knew\nall along.\n\nTiming does most of the work. An error found on blur is fixed while the person\nis still thinking about that field — the context is loaded, and the correction\ncosts seconds. The same error surfaced at submit arrives after they have moved\non, and now they must reload the context for every field at once.\n\nProximity does the rest. A banner saying \"3 errors\" makes the reader hunt; a\nmessage under the field makes it a correction.\n\n## Getting it wrong\n\n- **Clearing the field.** Unforgivable, and still common — especially with\n  passwords and long text.\n- **A top banner only**, so the person searches for which of twenty fields is\n  wrong.\n- **The database's message.** \"PG::UniqueViolation\" or \"constraint violated\" is\n  not an error message, it is a leak.\n- **Errors only on submit**, turning one wrong character into a full-form\n  re-read.\n- **Limits revealed only by breaking them.** If the maximum is 8 MB, say 8 MB\n  before the upload, not after.\n- **Colour alone**, so the failed field is invisible to a good number of\n  readers.\n- **Errors that persist** after the value is corrected, which teaches people to\n  ignore them.\n- **Blaming the person.** \"You entered an invalid value\" versus \"That reference\n  is already in use\".\n\n## Exemplars\n\n**Stripe's card fields** validate per field as you leave it, keep everything\ntyped, and name the specific problem — and the form is short enough that there\nis rarely more than one thing wrong at a time, which is itself part of the\ndesign.\n\n**GOV.UK's error summary pattern** is the most rigorously tested version: a\nsummary at the top whose entries are *links* to the fields, plus the message at\neach field. The summary is an addition, never a replacement — worth copying\nexactly when a form is long.\n\nThe extractable rule: **an error message is an instruction, not a verdict.** If\nit does not say what to do next, it has only told the person they are stuck.\n"}