Displaying error messages

DomValidation deliberately does not prescribe one fixed way to render errors.

Forms vary a lot between projects: sometimes the error belongs inside a <label>, sometimes after a <fieldset>, sometimes in a summary list at the top of the page.

The library's job is to tell us:

• which fields are invalid
• what message should be shown

Our job is to decide how that should appear in the document.

Reading the error list

After catching a ValidationException, iterate over the validator's last error list:

catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		// ...
	}
}

For each item:

• $name is the field name
• $message is the user-facing hint text

Pattern 1: add a data attribute and let CSS show the message

This is often the lightest approach because it keeps the HTML structure intact.

catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		$field = $form->querySelector("[name='$name']");
		$field?->parentElement?->dataset->validationError = $message;
	}
}

label[data-validation-error]::before {
	content: attr(data-validation-error);
	display: block;
	color: crimson;
	font-weight: bold;
	margin-bottom: 0.25rem;
}

This works well when each input sits neatly inside its own label or wrapper element.

Pattern 2: insert an element into the document

If we would rather produce a real element, we can do that too:

catch(ValidationException) {
	foreach($validator->getLastErrorList() as $name => $message) {
		$field = $form->querySelector("[name='$name']");
		if(!$field) {
			continue;
		}

		$error = $document->createElement("span");
		$error->classList->add("error-message");
		$error->textContent = $message;

		$field->before($error);
	}
}

This gives us more freedom if we want icons, ARIA attributes, or a stricter layout structure.

Pattern 3: build a summary list as well as field-level messages

Some forms benefit from both local messages and a top-level summary.

$summary = $document->createElement("ul");
$summary->classList->add("validation-summary");

foreach($validator->getLastErrorList() as $name => $message) {
	$item = $document->createElement("li");
	$item->textContent = "$name: $message";
	$summary->appendChild($item);
}

$form->prepend($summary);

This is especially useful for longer forms where the first invalid field may not be visible immediately.

When one field has more than one problem

The ErrorList combines multiple messages for the same field into one string, separated by ; .

For example, a required password field with a minimum length might produce:

This field is required; This field's value must contain at least 12 characters

That means we can treat each iteration item as the full message to show for that field.

Matching the right element

The simplest lookup is:

$field = $form->querySelector("[name='$name']");

That works well for normal inputs and selects. For checkbox groups, remember that the DOM element name may include [], while the submitted input key may not. In practice, it is often easiest to attach the message to the surrounding fieldset or container for the group rather than to one checkbox in isolation.

Keep the user on the same path

The best validation messages help the user continue without confusion:

• put the message close to the field when possible
• keep the wording plain and direct
• avoid showing the same message in too many places
• return early after adding the errors so invalid data is not processed

---

For the shape of the error data itself, continue with Understanding validation errors.