Validação de Formulários Simplificada com htmx

A validação de formulários não precisa significar escrever montanhas de JavaScript. Se você está cansado de gerenciar estado de validação, mensagens de erro e atualizações do DOM manualmente, o htmx oferece uma alternativa refrescantemente simples. Vamos explorar como implementar validação tanto do lado do cliente quanto do servidor com código mínimo e máxima experiência do usuário.

Validação do Lado do Cliente com htmx

Usando hx-validate para Feedback Instantâneo

A maneira mais simples de adicionar validação do lado do cliente é com hx-validate="true" no seu formulário. Isso instrui o htmx a verificar os atributos de validação HTML5 antes de enviar qualquer requisição:

<form hx-post="/submit" hx-validate="true">
  <input type="email" name="email" required>
  <input type="text" name="username" 
         pattern="[a-zA-Z0-9]{3,20}" 
         title="3-20 alphanumeric characters">
  <button type="submit">Submit</button>
</form>

Esta abordagem aproveita a validação integrada do navegador, fornecendo feedback instantâneo sem escrever nenhum JavaScript.

Regras Avançadas com a Extensão htmx-validation

Para cenários de validação mais complexos, a extensão htmx-validation oferece regras personalizadas:

<script src="https://unpkg.com/htmx.org/dist/ext/validate.js"></script>

<form hx-post="/submit" hx-ext="validate">
  <input name="password" type="password" 
         data-validate='{"required": true, "minLength": 8}'>
  <input name="confirm" type="password" 
         data-validate='{"equalTo": "password"}'>
  <button type="submit">Submit</button>
</form>

Esta extensão suporta funções de validação personalizadas, tornando-a perfeita para lógica de negócio que os atributos HTML5 não conseguem lidar.

Validação Inline do Lado do Servidor

Validação de Campo em Tempo Real

O padrão mais poderoso de validação de formulários htmx combina lógica do lado do servidor com atualizações inline. Veja como validar campos individuais conforme os usuários digitam:

<form hx-post="/register">
  <div>
    <label for="email">Email</label>
    <input name="email" id="email" 
           hx-post="/validate/email" 
           hx-trigger="blur, keyup delay:500ms"
           hx-target="next .error"
           hx-swap="innerHTML">
    <span class="error"></span>
  </div>
  <button type="submit">Register</button>
</form>

Seu endpoint do servidor retorna feedback de validação:

# Python/Flask example
@app.route('/validate/email', methods=['POST'])
def validate_email():
    email = request.form.get('email')
    if not email or '@' not in email:
        return '<span class="text-red">Invalid email format</span>'
    if email_exists_in_db(email):
        return '<span class="text-red">Email already taken</span>'
    return '<span class="text-green">✓ Available</span>'

Validação Completa de Formulário com Respostas Parciais

Para validação completa de formulário, retorne o formulário inteiro com estados de erro:

<form id="contact-form" 
      hx-post="/contact" 
      hx-target="this" 
      hx-swap="outerHTML">
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>

O servidor retorna o formulário com classes de erro e mensagens quando a validação falha, ou uma mensagem de sucesso quando passa.

Armadilhas Comuns e Soluções

Atributos de Botão vs Formulário

Um erro frequente é colocar hx-post no botão de envio em vez do formulário:

<!-- Errado: validação não será acionada -->
<form hx-validate="true">
  <button hx-post="/submit">Submit</button>
</form>

<!-- Correto: validação funciona -->
<form hx-post="/submit" hx-validate="true">
  <button type="submit">Submit</button>
</form>

Tratamento de Eventos de Validação

O htmx fornece eventos para controle refinado sobre o fluxo de validação:

// Interceptar antes da validação
document.body.addEventListener('htmx:configRequest', function(evt) {
  if (evt.target.matches('[data-confirm]')) {
    evt.preventDefault()
    if (confirm(evt.target.dataset.confirm)) {
      evt.detail.issueRequest()
    }
  }
})

// Tratar erros de validação do servidor
document.body.addEventListener('htmx:responseError', function(evt) {
  if (evt.detail.xhr.status === 422) {
    // Exibir erros de validação do servidor
    const errors = JSON.parse(evt.detail.xhr.response)
    showValidationErrors(errors)
  }
})

Melhores Práticas para Validação Acessível

Sempre inclua atributos ARIA adequados para leitores de tela:

<input name="email" 
       aria-invalid="true" 
       aria-describedby="email-error">
<span id="email-error" role="alert">
  Please enter a valid email
</span>

Use hx-trigger="blur" em vez de keyup para campos onde validação constante pode ser irritante, como senhas. Para busca ou verificação de disponibilidade de nome de usuário, keyup delay:500ms fornece um bom equilíbrio.

Conclusão

A validação de formulários htmx se destaca mantendo a lógica de validação onde ela pertence—no servidor—enquanto fornece a experiência suave e responsiva que os usuários esperam. Seja escolhendo validação do lado do cliente para feedback instantâneo ou validação do lado do servidor para regras complexas, o htmx reduz o JavaScript que você escreve enquanto melhora a experiência do usuário. Comece com hx-validate="true" para necessidades básicas, depois adicione progressivamente validação inline para um formulário polido e pronto para produção.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.