O que é o HTMX

O HTMX e uma biblioteca JavaScript minimalista que expande o HTML com atributos especiais para fazer requisições HTTP, atualizar partes da página e reagir a eventos, tudo sem escrever JavaScript manualmente. A ideia central e simples: deixar o HTML fazer o trabalho que normalmente exigiria um framework complexo.

Criado por Carson Gross, o HTMX e a evolução do antigo intercooler.js. Ele se baseia na filosofia de que o HTML original do Tim Berners-Lee era poderoso, mas ficou limitado ao longo dos anos porque links só fazem GET e formulários só fazem GET e POST. O HTMX remove essas limitações sem adicionar uma camada de abstração pesada.

Em 2023, o projeto Misago (fórum open source em Django) publicou um relato detalhado de como removeu o React do codebase e adotou o HTMX para a interface. O resultado foi uma redução significativa de complexidade, menos dependências e um frontend mais fácil de manter. Esse relato viralizou na comunidade e impulsionou ainda mais a adoção do HTMX.

Como funciona

O HTMX funciona adicionando atributos HTML especiais (prefixados com hx-) aos elementos da página. Quando o usuário interage com esses elementos, o HTMX envia uma requisição HTTP para o servidor e usa a resposta HTML para atualizar uma parte específica da página.

Por exemplo, um botão com hx-get="/fragmento" e hx-target="#resultado" faz uma requisição GET para /fragmento quando clicado e substitui o conteúdo de #resultado com o HTML retornado pelo servidor. Não e necessário nenhum JavaScript adicional, nenhum estado gerenciado no cliente, nenhum bundle para compilar.

O servidor continua sendo a fonte de verdade. Em vez de retornar JSON que o frontend converte em HTML, o backend retorna HTML diretamente. Isso e um retorno ao modelo clássico de renderização no servidor, mas com interatividade moderna e sem recarregar a página inteira.

💡
Dica

HTMX funciona com qualquer linguagem de backend. Django, FastAPI, Rails, Laravel, Go, .NET: se o servidor consegue retornar HTML, o HTMX funciona.

Principais recursos

Os principais atributos do HTMX que você vai usar no dia a dia:

  • hx-get / hx-post / hx-put / hx-delete / hx-patch: define o método HTTP e a URL da requisição.
  • hx-target: seleciona qual elemento da página será atualizado com a resposta do servidor (aceita seletores CSS).
  • hx-swap: define como o conteúdo será inserido: substituir o innerHTML, substituir o elemento inteiro (outerHTML), adicionar antes/depois, etc.
  • hx-trigger: controla qual evento dispara a requisição (click, change, submit, revealed para scroll infinito, etc.).
  • hx-push-url: atualiza a URL do navegador após a requisição, mantendo a navegabilidade com botão de voltar funcionando.
  • hx-indicator: mostra um spinner ou indicador de loading enquanto a requisição esta em andamento.
  • hx-boost: converte todos os links e formulários de uma secao para requisições ÁJAX automaticamente, acelerando a navegação.

Além dos atributos, o HTMX tem suporte a eventos JavaScript para casos avançados, extensões oficiais para websockets e SSE (Server-Sent Events), e integração com Alpine.js para quem precisa de um pouco mais de reatividade no cliente.

Como começar: instalação e configuração

A instalação do HTMX e trivial. Você pode incluir via CDN ou instalar via npm.

Via CDN (mais simples):

<script src="https://unpkg.com/[email protected]"></script>

Via npm (para projetos que já tem pipeline de build):

npm install htmx.org

Depois e só importar no seu arquivo principal:

import 'htmx.org';

Não ha configuração obrigatória. O HTMX já funciona ao ser incluído na página. Para configurações avançadas como timeout, histórico de URLs ou tratamento de erros, use o objeto htmx.config antes de carregar a biblioteca.

Exemplo prático

Imagine um sistema de lista de tarefas onde o usuário pode adicionar itens sem recarregar a página. Em React, isso exigiria estado, handlers, fetch e reconciliação do DOM. Com HTMX e um backend Django:

Template HTML:

<form hx-post="/tarefas/" hx-target="#lista" hx-swap="beforeend" hx-on::after-request="this.reset()">
  <input type="text" name="titulo" placeholder="Nova tarefa..." required>
  <button type="submit">Adicionar</button>
</form>

<ul id="lista">
  {% for tarefa in tarefas %}
  <li>{{ tarefa.titulo }}</li>
  {% endfor %}
</ul>

View Django (retorna apenas o fragmento HTML, não a página inteira):

def adicionar_tarefa(request):
    if request.method == 'POST':
        titulo = request.POST.get('titulo')
        tarefa = Tarefa.objects.create(titulo=titulo)
        # Retorna apenas o <li> novo, não a página inteira
        return render(request, 'tarefas/_item.html', {'tarefa': tarefa})

O HTMX pega o <li> retornado pelo servidor e insere no final da #lista, sem JavaScript adicional, sem gerenciamento de estado no cliente, sem bundle.

🚀
Pro tip

Use o atributo hx-boost="true" no elemento body para converter automaticamente todos os links da página em requisições ÁJAX. O usuário tem a sensação de SPA sem você precisar escrever uma linha de JavaScript de roteamento.

Comparação com alternativas

O HTMX não e a única alternativa ao React para quem quer simplicidade:

  • React / Next.js: a escolha padrão para SPAs complexas com muito estado no cliente, roteamento avançado e equipes grandes de frontend. Overhead de configuração e bundle justificável quando a interatividade e muito alta.
  • Vue.js / Nuxt: curva de aprendizado menor que React, ainda assim um framework completo com reatividade no cliente. Bom meio-termo entre HTMX e React.
  • Alpine.js: mais próximo do HTMX em filosofia, mas focado em reatividade JavaScript no cliente em vez de requisições ao servidor. Complementa bem o HTMX para pequenas interações locais.
  • Turbo (Hotwire): solução similar ao HTMX, parte do ecossistema Rails/Stimulus. Tem mais convenções e e mais opinativo, o que pode ser bom ou ruim dependendo do projeto.
  • Astro: framework de renderização no servidor com ilhas de interatividade. Diferente do HTMX, mas compartilha a filosofia de enviar menos JavaScript ao cliente.

O HTMX ganha quando o projeto e principalmente orientado a servidor com interatividade moderada. React ganha quando o estado no cliente e complexo e a UI tem muita lógica de componente isolada.

Pontos positivos e limitações

Pontos positivos:

  • Bundle minúsculo: menos de 14KB minificado e gzipado
  • Sem etapa de build obrigatória para o frontend
  • Funciona com qualquer linguagem de backend
  • Curva de aprendizado muito baixa para quem já conhece HTML
  • Sem gerenciamento de estado no cliente para a maioria dos casos
  • SEO natural: o HTML vem do servidor, sem hidratação

Limitações reais:

  • Não substitui React para UIs altamente reativas com muito estado local (editores, dashboards em tempo real, etc.)
  • Ausência de tipagem e ferramentas de dev como DevTools do React
  • Requer que o backend saiba retornar fragmentos HTML, o que pode exigir refatoração de APIs existentes que retornam JSON
  • Communidade menor que React, menos recursos em português
⚠️
Atenção

Se você tem uma API REST em JSON compartilhada com um app mobile, não faz sentido migrar para HTMX sem uma camada de backend nova. HTMX funciona melhor com backend dedicado que retorne HTML.

Casos de uso reais

1. Sistemas internos e backoffices: ferramentas de gestão usadas por uma equipe pequena não precisam da complexidade de um SPA completo. HTMX com Django ou Rails entrega a interatividade necessária com muito menos código.

2. Blogs e CMS com interatividade moderada: comentários, likes, filtros de busca, paginação sem reload, formulários de newsletter. Tudo isso funciona perfeitamente com HTMX sem um framework pesado.

3. Projetos de desenvolvedor solo ou equipes pequenas: quando você não tem um time de frontend dedicado, HTMX reduz a pilha de tecnologias a manter. Um desenvolvedor backend pode criar interfaces funcionais sem dominar React, TypeScript e o ecosistema moderno de frontend.

4. Migrações graduais de aplicações legadas: substituir partes de uma aplicação server-rendered tradicional por interatividade moderna sem reescrever tudo. HTMX se encaixa como progressividade, não como substituição completa.

Dicas e boas práticas

💡
Dica

Estruture seus templates em fragmentos reutilizáveis desde o inicio. A view que retorna a página inteira e a view que retorna o fragmento devem reutilizar o mesmo template parcial.

💡
Dica

Use o cabeçalho HTTP HX-Request: true que o HTMX envia automaticamente para diferenciar requisições HTMX de requisições normais no backend. Isso permite retornar fragmento ou página inteira na mesma URL.

🚀
Pro tip

Combine HTMX com Alpine.js para casos onde você precisa de reatividade local (toggles, contadores, validação de formulário) sem fazer uma requisição ao servidor. Os dois se complementam perfeitamente.

🔴
Cuidado

Não use HTMX para funcionalidades que dependem de estado complexo no cliente, como um editor de texto rico ou um canvas interativo. Para esses casos, um componente React ou Vue ainda e a melhor opcao.

Vale a pena?

O HTMX vale muito a pena para quem esta cansado da complexidade do ecossistema moderno de frontend. Se o seu projeto e uma aplicação web com interatividade moderada, backend monolítico e equipe pequena, a troca de React por HTMX pode simplificar radicalmente a stack sem sacrificar a experiência do usuário.

Para quem não vale: aplicações com UI altamente dinâmica, muito estado no cliente (tipo um editor colaborativo ou dashboard em tempo real com dezenas de widgets), ou projetos onde a API JSON já existe e e consumida por mobile e web. Nesses casos, React ou Vue ainda são a escolha certa.

O próximo passo e ler a documentação oficial em htmx.org, que é extremamente bem escrita e concisa. Depois, experimente substituir uma pequena parte de um projeto existente, como um formulário ou uma tabela com paginação. O resultado vai impressionar pela simplicidade.