SGDS Form Validation Pattern

SGDS form components integrate with the browser's ElementInternals API so they behave like native HTML form controls — they participate in <form> submission, FormData, and constraint validation automatically.

Prerequisites

See [sgds-components](../sgds-components/SKILL.md) for installation and framework integration.

All form components must be placed inside a <form> element and given a name attribute to participate in form submission.

Quick Decision Guide

Show native HTML validation messages? → Add hasFeedback to each form component

Prevent submit when fields are invalid? → Built-in — no extra code needed

Read submitted field values? → Use new FormData(event.target) in the submit handler

Disable SGDS validation per component? → noValidate prop on <sgds-input>, <sgds-textarea>, <sgds-combo-box>, <sgds-select>, <sgds-datepicker>, <sgds-quantity-toggle>, or <sgds-file-upload>

Disable SGDS validation for the whole form? → novalidate on the <form> element

Run 3rd-party validation (e.g. Zod)? → Disable SGDS validation first, then call setInvalid(bool) and set invalidFeedback programmatically

How Validation Is Triggered

SGDS validation is layered:

1. onChange (after blur) — validates when the user leaves a field; shows feedback if hasFeedback is set
2. onSubmit — final validation pass fires before submission; blocks the form if any field is invalid
3. onReset — clears all validity states and field values when the form is reset

Disabled components skip validation entirely.

hintText and Error Message Placement

On most form components (<sgds-input>, <sgds-textarea>, <sgds-select>, <sgds-combo-box>, <sgds-quantity-toggle>, <sgds-file-upload>), hintText and the error message share the same space below the input container:

• When the field is invalid (and hasFeedback is set), the error message replaces hintText.
• When the error is resolved, hintText reappears.

<sgds-checkbox-group> and <sgds-radio-group> behave differently — hintText is rendered in the label row above the options and remains visible at all times. The error message appears separately below the options.

Activating Feedback Display

Constraint validation runs regardless of hasFeedback, but the visible error message only renders when hasFeedback is present. The hasFeedback prop accepts:

You can also override the displayed message with invalidFeedback:

<sgds-input
  name="email"
  label="Email"
  type="email"
  required
  hasFeedback="both"
  invalidFeedback="Please enter a valid email address"
></sgds-input>

Constraint Validations by Component

Full Form Example

<form id="my-form" class="d-flex-column">
  <sgds-input
    label="First Name"
    name="firstName"
    required
    hasFeedback="both"
    pattern="[A-Za-z ]+"
    invalidFeedback="Letters only"
  ></sgds-input>

  <sgds-datepicker label="Appointment Date" name="appointmentDate" required hasFeedback></sgds-datepicker>

  <sgds-radio-group label="Gender" name="gender" required hasFeedback>
    <sgds-radio value="female">Female</sgds-radio>
    <sgds-radio value="male">Male</sgds-radio>
  </sgds-radio-group>

  <sgds-checkbox-group label="Food Preference" name="food" required hasFeedback hintText="Select at least one option">
    <sgds-checkbox value="vegetarian">Vegetarian</sgds-checkbox>
    <sgds-checkbox value="halal">Halal</sgds-checkbox>
  </sgds-checkbox-group>

  <sgds-textarea label="Comments" name="comments" required minlength="3" hasFeedback></sgds-textarea>

  <sgds-button type="submit">Submit</sgds-button>
  <sgds-button type="reset" variant="ghost">Reset</sgds-button>
</form>

Reading Form Values via FormData

Use the native FormData API in the submit handler. Access sgds-file-upload files separately via the component's selectedFiles property:

<script>
  const form = document.getElementById("my-form");

  form.addEventListener("submit", event => {
    event.preventDefault();
    const formData = new FormData(event.target);

    const firstName = formData.get("firstName");
    const gender = formData.get("gender");
    const comments = formData.get("comments");

    // File upload files are not in FormData automatically
    const fileUpload = document.querySelector("sgds-file-upload");
    for (let i = 0; i < fileUpload.selectedFiles.length; i++) {
      formData.append("file" + i, fileUpload.selectedFiles[i]);
    }

    // Submit formData to server
  });
</script>

Custom Validation (Disabling SGDS Validation)

For 3rd-party validation libraries (e.g. Zod) or fully custom logic, disable SGDS's built-in validation first, then call setInvalid(bool) and update invalidFeedback in response to input events.

Option 1 — Disable per component with noValidate

Currently supported on <sgds-input>, <sgds-textarea>, <sgds-combo-box>, <sgds-datepicker>, <sgds-file-upload>, <sgds-select>, <sgds-quantity-toggle>, <sgds-radio-group>, <sgds-checkbox>, and <sgds-checkbox-group>.

<sgds-input
  noValidate
  id="keys-input"
  name="keys"
  label="Keys"
  hintText="Cannot start with special characters"
  hasFeedback="both"
></sgds-input>

<script>
  const input = document.getElementById("keys-input");

  input.addEventListener("sgds-input", e => {
    if (/^[^a-zA-Z0-9]/.test(e.target.value)) {
      e.target.setInvalid(true);
      e.target.invalidFeedback = "Keys cannot start with special characters";
    } else {
      e.target.setInvalid(false);
    }
  });
</script>

Option 2 — Disable at form level with novalidate

Adding novalidate to the <form> element disables constraint validation and SGDS validation for all child components. Then apply setInvalid logic per field.

<form id="custom-form" novalidate class="d-flex-column">
  <sgds-input id="keys-input" name="keys" label="Keys" hasFeedback="both"></sgds-input>

  <sgds-textarea id="bio-textarea" name="bio" label="Bio" hasFeedback></sgds-textarea>
</form>

<script>
  document.getElementById("keys-input").addEventListener("sgds-input", e => {
    if (/^[^a-zA-Z0-9]/.test(e.target.value)) {
      e.target.setInvalid(true);
      e.target.invalidFeedback = "Invalid key format";
    } else {
      e.target.setInvalid(false);
    }
  });

  document.getElementById("bio-textarea").addEventListener("sgds-input", e => {
    if (e.target.value.length < 10) {
      e.target.setInvalid(true);
      e.target.invalidFeedback = "Bio must be at least 10 characters";
    } else {
      e.target.setInvalid(false);
    }
  });
</script>

setInvalid(bool) Method

Pair setInvalid(true) with setting the invalidFeedback property on the element to control the displayed message.

Custom Validation Support Status

For AI agents

1. Always place SGDS form components inside a <form> element with name attributes for them to participate in form submission and FormData.
2. hasFeedback must be present on a form component for the error message to visually appear — constraint validation alone does not show UI feedback.
3. To show both the invalid border style and the error message text, use hasFeedback="both". A plain boolean hasFeedback shows the message text only.
4. Use invalidFeedback to override the browser's native constraint validation message with a custom string.
5. Constraint validation and form submission blocking are built-in — do not add extra submit event listeners to replicate this behaviour.
6. Use new FormData(event.target) in the submit handler to read values. For file uploads, read selectedFiles directly from the <sgds-file-upload> element.
7. When using custom/3rd-party validation, add noValidate on the component (or novalidate on the form), then call element.setInvalid(true/false) and set element.invalidFeedback inside the relevant event listener (sgds-input for inputs/textareas, sgds-change-date for datepicker, sgds-change for select/combo-box/radio-group/checkbox-group/quantity-toggle, sgds-add-files/sgds-remove-file for file-upload).
8. All form components (<sgds-input>, <sgds-textarea>, <sgds-datepicker>, <sgds-combo-box>, <sgds-select>, <sgds-quantity-toggle>, <sgds-radio-group>, <sgds-checkbox>, <sgds-checkbox-group>, and <sgds-file-upload>) fully support custom validation via noValidate + setInvalid.
9. The reset button (type="reset") automatically clears all validity states and values — no extra reset logic is needed.
10. Disabled components are excluded from constraint validation and will never block form submission.