O Novo Elemento HTML de Geolocalização

Se você já configurou navigator.geolocation.getCurrentPosition(), conhece a rotina: escrever o callback, tratar o erro, gerenciar o estado de permissão e torcer para que o navegador não bloqueie silenciosamente a solicitação porque o usuário a dispensou muitas vezes. O novo elemento HTML <geolocation> adota uma abordagem completamente diferente—geolocalização declarativa em HTML, gerenciada pelo próprio navegador.

Aqui está o que é, como funciona e o que você precisa saber antes de usá-lo.

O Que É o Elemento HTML <geolocation>?

O elemento HTML <geolocation> é um botão experimental controlado pelo navegador que permite aos usuários compartilhar sua localização diretamente da página. Em vez do seu JavaScript disparar uma solicitação de permissão, o próprio usuário ativa o controle. O navegador gerencia o fluxo de permissão, e você escuta o resultado.

Foi lançado no Chrome 144. No início de 2026, isso permanece como uma funcionalidade liderada pelo Chromium e ainda não foi implementada em outros motores. Trate-o como algo para experimentar, não para lançar universalmente sem um fallback. Você pode acompanhar o status atual de implementação em https://caniuse.com/mdn-html_elements_geolocation.

O Problema com a API de Geolocalização

A API navigator.geolocation é imperativa. Seu script chama getCurrentPosition(), o navegador decide se mostra uma solicitação, e se o usuário dispensou essa solicitação várias vezes, o Chrome pode bloqueá-la silenciosamente por um período de tempo. Sem erro, sem feedback—apenas silêncio.

A lacuna de contexto piora a situação. Uma solicitação que aparece sem explicação é negada reflexivamente. Essa negação pode se tornar persistente, e não há uma maneira óbvia para os usuários desfazê-la.

Como a Geolocalização Declarativa em HTML Resolve Isso

O elemento <geolocation> inverte o modelo. O usuário clica no botão. Esse clique é o sinal de permissão. O navegador sabe que a solicitação veio de uma ação deliberada do usuário, o que ajuda a evitar cenários de bloqueio silencioso e dá aos usuários um caminho de recuperação mais claro se eles negaram acesso anteriormente.

A interface HTMLGeolocationElement expõe o resultado diretamente no elemento:

<geolocation onlocation="handleLocation(event)"></geolocation>

function handleLocation(event) {
  if (event.target.position) {
    const { latitude, longitude } = event.target.position.coords;
    console.log(latitude, longitude);
  } else if (event.target.error) {
    console.error(event.target.error.message);
  }
}

O elemento expõe as propriedades position e error, e você escuta eventos como location quando o navegador retorna um resultado.

Atributos Principais

• autolocate — Se a permissão foi concedida anteriormente, dispara o evento location no carregamento da página sem exigir um clique. Não faz nada se a permissão ainda não foi concedida.
• watch — Espelha watchPosition(), disparando continuamente conforme o dispositivo se move.
• accuracymode — Aceita "precise" ou "approximate". O modo preciso mapeia para enableHighAccuracy: true e muda o ícone do botão para uma mira. Note que em desktops a diferença é frequentemente negligenciável—teste em um dispositivo móvel ao ar livre para ver variação real.

Uma peculiaridade que vale a pena conhecer: você só pode usar até três elementos <geolocation> por página. Exceda isso e todos eles param de funcionar.

O elemento ainda depende do mesmo modelo de segurança subjacente da API de Geolocalização, que requer um contexto seguro (HTTPS) e permissão explícita do usuário.

API de Geolocalização vs Elemento HTML de Geolocalização: Qual Você Deve Usar?

Neste momento, ambos. O elemento HTML <geolocation> não substitui navigator.geolocation—ele o envolve. Use o elemento onde for suportado e faça fallback graciosamente:

<geolocation onlocation="updateMap()">
  <!-- Renderizado apenas em navegadores que não suportam <geolocation> -->
  <button onclick="navigator.geolocation.getCurrentPosition(updateMap)">
    Usar minha localização
  </button>
</geolocation>

Navegadores que suportam suprimem o conteúdo filho. Navegadores que não suportam renderizam o botão de fallback. Se você quiser uma abordagem mais automatizada, há um polyfill no npm que substitui por um elemento customizado baseado na API padrão.

A detecção de funcionalidade é direta:

if ('HTMLGeolocationElement' in window) {
  // elemento suportado
} else {
  // use navigator.geolocation
}

A Estilização Tem Limites Rígidos

O elemento parece um botão, mas não se comporta como um do ponto de vista CSS. O navegador impõe restrições para prevenir padrões enganosos: opacity é travada em 1, o contraste entre texto e fundo deve ser de pelo menos 3:1, e transformações distorcidas são bloqueadas. Se o contraste ou tamanho da fonte cair abaixo do limite mínimo, o botão não desativa visualmente—ele simplesmente para de funcionar. Você pode usar a pseudo-classe :granted para estilizar o botão após a permissão ser concedida.

Para Onde Isso Está Indo

O elemento <geolocation> é o primeiro de uma série planejada de elementos específicos de capacidades. Um elemento <usermedia> para acesso à câmera e microfone já está em origin trial. O padrão—declarativo, iniciado pelo usuário, mediado pelo navegador—é claramente a direção que a plataforma está tomando.

Conclusão

O elemento <geolocation> representa uma mudança significativa em como os navegadores lidam com permissões sensíveis. Ao mover o gatilho do script para a ação do usuário, ele evita muitas das armadilhas de bloqueio silencioso da API imperativa e dá aos usuários controle mais claro sobre quando e se compartilham sua localização. O suporte dos navegadores ainda é limitado, mas o padrão de fallback é limpo e a superfície da API é mínima. Comece a experimentar com aprimoramento progressivo hoje—a UX de permissão é genuinamente melhor para os usuários, e o modelo declarativo é para onde a plataforma web está indo.

Perguntas Frequentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.