Pourquoi les champs personnalisés posent souvent problème

Créer un composant visuel de formulaire est assez simple. Créer un vrai champ de formulaire est beaucoup plus exigeant.

Un composant <rating-input>, <date-range-picker> ou <tag-selector> ne doit pas seulement afficher une interface agréable. Il doit aussi participer à l’envoi du formulaire, exposer une valeur, gérer l’état disabled, signaler ses erreurs, fonctionner au clavier et rester compréhensible pour les technologies d’assistance.

Historiquement, beaucoup de composants personnalisés contournaient le problème avec un champ caché :

<input type="hidden" name="rating" value="4" />

Cette technique fonctionne pour envoyer une valeur, mais elle reste fragile. Elle ne donne pas automatiquement accès à la validation native, à form.reset(), aux états internes du formulaire ou à une intégration propre avec [FormData](/articles/formulaires-html-donnees-utilisateur).

Les form-associated custom elements permettent d’aller plus loin : créer des Web Components capables de se comporter comme de vrais contrôles de formulaire. Si vous avez déjà travaillé avec les Custom Elements, c’est une extension naturelle de cette approche.

Le principe des form-associated custom elements

Un custom element devient associé à un formulaire en déclarant une propriété statique formAssociated à true. Le navigateur lui fournit alors un objet interne, appelé ElementInternals, qui sert de passerelle avec les mécanismes natifs du formulaire.

class RatingInput extends HTMLElement {
  static formAssociated = true;

  private internals: ElementInternals;
  private value = "0";

  constructor() {
    super();
    this.internals = this.attachInternals();
  }
}

customElements.define("rating-input", RatingInput);

La ligne importante est this.attachInternals(). Elle permet au composant de définir sa valeur de formulaire, son état de validation et certaines métadonnées d’accessibilité.

Ce mécanisme est particulièrement utile pour des composants qui représentent une seule valeur métier : notation, choix de couleur, intervalle de dates, sélection multiple, coordonnées, tags, etc.

Créer un champ de notation utilisable dans un formulaire

Prenons un exemple concret : un champ de notation de 1 à 5. Côté HTML, on veut pouvoir l’utiliser comme un champ natif.

<form id="review-form">
  <label for="score">Note</label>
  <rating-input id="score" name="score" required></rating-input>

  <button type="submit">Envoyer</button>
</form>

Le composant doit exposer une valeur sous le nom score lors de la soumission.

class RatingInput extends HTMLElement {
  static formAssociated = true;
  static observedAttributes = ["disabled", "required"];

  private internals: ElementInternals;
  private shadow: ShadowRoot;
  private currentValue = "";

  constructor() {
    super();
    this.internals = this.attachInternals();
    this.shadow = this.attachShadow({ mode: "open" });
  }

  connectedCallback() {
    this.render();
    this.updateFormValue();
    this.updateValidity();
  }

  attributeChangedCallback() {
    this.updateValidity();
  }

  get value() {
    return this.currentValue;
  }

  set value(nextValue: string) {
    this.currentValue = nextValue;
    this.updateFormValue();
    this.updateValidity();
    this.render();
  }

  private updateFormValue() {
    this.internals.setFormValue(this.currentValue);
  }

  private updateValidity() {
    if (this.hasAttribute("required") && !this.currentValue) {
      this.internals.setValidity(
        { valueMissing: true },
        "Veuillez choisir une note."
      );
      return;
    }

    this.internals.setValidity({});
  }

  private render() {
    const disabled = this.hasAttribute("disabled");

    this.shadow.innerHTML = `
      <style>
        :host {
          display: inline-flex;
          gap: 0.25rem;
        }

        button {
          font: inherit;
          min-width: 2.25rem;
          min-height: 2.25rem;
          border: 1px solid currentColor;
          border-radius: 999px;
          background: transparent;
          cursor: pointer;
        }

        button[aria-pressed="true"] {
          background: currentColor;
          color: white;
        }

        button:disabled {
          cursor: not-allowed;
          opacity: 0.5;
        }
      </style>

      ${[1, 2, 3, 4, 5]
        .map(
          (score) => `
            <button
              type="button"
              value="${score}"
              aria-pressed="${this.currentValue === String(score)}"
              ${disabled ? "disabled" : ""}
            >
              ${score}
            </button>
          `
        )
        .join("")}
    `;

    this.shadow.querySelectorAll("button").forEach((button) => {
      button.addEventListener("click", () => {
        this.value = button.getAttribute("value") ?? "";
      });
    });
  }
}

customElements.define("rating-input", RatingInput);

Ce composant peut maintenant être lu via [FormData](/articles/formulaires-html-donnees-utilisateur), comme un champ standard.

const form = document.querySelector<HTMLFormElement>("#review-form");

form?.addEventListener("submit", (event) => {
  event.preventDefault();

  const data = new FormData(form);
  console.log(data.get("score"));
});

Gérer la validation native

La méthode setValidity() permet au composant de déclarer son état de validation. Quand l’objet passé est vide, le champ est valide. Quand il contient une contrainte, comme valueMissing, rangeUnderflow ou customError, le champ devient invalide.

this.internals.setValidity(
  { customError: true },
  "La note doit être comprise entre 1 et 5."
);

L’intérêt est que le formulaire peut ensuite utiliser les méthodes natives :

const form = document.querySelector<HTMLFormElement>("form");

if (!form?.reportValidity()) {
  console.log("Le formulaire contient des erreurs.");
}

Cette approche s’intègre beaucoup mieux avec les pratiques décrites dans l’article sur les formulaires accessibles. Le composant ne doit pas seulement bloquer une soumission invalide : il doit aussi produire un retour compréhensible.

Attention toutefois : la validation native ne dispense pas de validation serveur. Elle améliore l’expérience utilisateur, mais elle ne sécurise pas les données reçues côté backend.

Prendre en charge reset, disabled et état initial

Un vrai champ de formulaire doit aussi réagir à form.reset(). Les form-associated custom elements peuvent implémenter une méthode spéciale : formResetCallback().

class RatingInput extends HTMLElement {
  static formAssociated = true;

  private internals: ElementInternals;
  private currentValue = "";
  private defaultValue = "";

  constructor() {
    super();
    this.internals = this.attachInternals();
  }

  connectedCallback() {
    this.defaultValue = this.getAttribute("value") ?? "";
    this.value = this.defaultValue;
  }

  formResetCallback() {
    this.value = this.defaultValue;
  }

  get value() {
    return this.currentValue;
  }

  set value(nextValue: string) {
    this.currentValue = nextValue;
    this.internals.setFormValue(nextValue);
  }
}

Il existe aussi formDisabledCallback(disabled: boolean), utile pour synchroniser l’état interne du composant quand un formulaire ou un fieldset est désactivé.

formDisabledCallback(disabled: boolean) {
  this.toggleAttribute("disabled", disabled);
}

Cela évite de traiter disabled comme un simple détail visuel. Un champ désactivé ne doit pas être modifiable, ne doit généralement pas être focusable et ne doit pas être soumis avec le formulaire.

Accessibilité : ne pas se cacher derrière le Shadow DOM

Le Shadow DOM aide à encapsuler la structure interne d’un composant, mais il ne rend pas automatiquement un composant accessible. Pour un champ personnalisé, il faut penser au rôle, au nom accessible, au focus clavier et aux retours d’erreur.

Une stratégie simple consiste à utiliser des éléments natifs à l’intérieur du shadow root, comme des boutons, des inputs ou des éléments focusables standards. Dans notre exemple, les boutons conservent un comportement clavier prévisible.

Pour exposer certaines informations au navigateur, ElementInternals permet aussi de définir des propriétés ARIA par défaut.

this.internals.role = "radiogroup";
this.internals.ariaRequired = this.hasAttribute("required") ? "true" : "false";

Il faut cependant rester prudent : si votre composant reproduit un groupe de boutons radio, l’idéal est parfois d’utiliser directement des boutons radio natifs stylés. Les composants personnalisés sont pertinents quand le modèle d’interaction dépasse ce que le HTML standard fournit clairement.

Cette logique rejoint le progressive enhancement : partir du comportement le plus robuste, puis enrichir uniquement quand cela apporte une vraie valeur.

Styliser sans enfermer le composant

Un composant réutilisable doit pouvoir être intégré dans plusieurs interfaces. Évitez donc de figer toutes les couleurs, tailles et marges dans le Shadow DOM.

Les custom properties CSS permettent d’exposer des points de personnalisation simples.

:host {
  --rating-size: 2.25rem;
  --rating-gap: 0.25rem;
  display: inline-flex;
  gap: var(--rating-gap);
}

button {
  inline-size: var(--rating-size);
  block-size: var(--rating-size);
}

Ces variables peuvent ensuite être reliées à un système plus large de design tokens. Le composant reste encapsulé, mais il n’est pas isolé du langage visuel de l’application.

Si votre composant est rendu côté serveur, vous pouvez également étudier le Declarative Shadow DOM, qui permet de fournir une structure encapsulée dès le HTML initial.

Quand utiliser cette technique

Les form-associated custom elements sont adaptés quand vous avez besoin d’un contrôle de formulaire réellement réutilisable, indépendant d’un framework, et capable de fonctionner dans plusieurs contextes : application React, Vue, Nuxt, Next, page statique ou back-office traditionnel.

Ils sont moins indiqués pour des champs simples que HTML couvre déjà très bien. Avant de créer un composant personnalisé, vérifiez toujours si un input, un select, un textarea, un groupe de radios ou une combinaison de ces éléments suffit.

La bonne question n’est pas : « puis-je créer mon propre champ ? » mais plutôt : « est-ce que ce champ apporte un modèle d’interaction que le HTML natif ne représente pas correctement ? ».

Bonnes pratiques à retenir

Un form-associated custom element doit être conçu comme un vrai contrat avec le formulaire. Il doit exposer une valeur claire, respecter name, gérer disabled, participer à la validation, réagir à reset et rester utilisable au clavier.

Il doit aussi rester sobre. Plus un composant de formulaire invente ses propres conventions, plus il risque de surprendre les utilisateurs, les développeurs et les outils d’assistance.

Utilisés avec discernement, les form-associated custom elements permettent de créer des composants natifs, durables et interopérables. Ils constituent une excellente option pour construire une bibliothèque d’interface qui ne dépend pas entièrement d’un framework, tout en conservant les fondamentaux du web : HTML, formulaires, accessibilité et amélioration progressive.