Apresentação do elemento HTML <geolocation>

Mari Viana

Minh Le

Thomas Steiner

Publicado em 13 de janeiro de 2026

A partir do Chrome 144, você pode usar o novo elemento HTML <geolocation>. Esse elemento representa uma grande mudança na forma como os sites solicitam dados de localização do usuário, passando de solicitações de permissão acionadas por script para uma experiência declarativa e orientada à ação do usuário. Ele reduz o código boilerplate necessário para processar estados e erros de permissão e fornece um sinal mais forte da intenção do usuário, o que ajuda a evitar intervenções do navegador (como bloqueios silenciosos).

Esse lançamento é resultado de testes extensivos no mundo real e de uma discussão rigorosa com a comunidade de padrões da Web. Para entender a utilidade desse elemento, é importante examinar a história do desenvolvimento dele e os dados que impulsionaram o design.

De <permission> genérico a <geolocation> específico

O elemento <geolocation> é a mais recente evolução da iniciativa de controle de permissão incorporado à página, que foi proposta inicialmente como um elemento <permission> genérico com um atributo type (consulte a explicação original). O valor do atributo type (por exemplo, "geolocation") determina o tipo de permissão solicitada. Por exemplo, a proposta inicial inclui valores como câmera, microfone e geolocalização.

Validação do conceito

Realizamos um teste de origem para o elemento <permission> genérico do Chrome 126 ao 143. O objetivo desse teste era verificar a hipótese de que um botão dedicado e contextualizado melhoraria a confiança e a tomada de decisões dos usuários.

Os resultados desse teste de origem apoiaram a validação deste conceito principal:

• O Zoom informou uma redução de 46,9% nos erros de captura de câmera ou microfone (como bloqueadores no nível do sistema) ao usar o elemento para orientar os usuários na recuperação.
• A Immobiliare.it teve um aumento de 20% nos fluxos de geolocalização bem-sucedidos.
• O ZapImóveis observou uma taxa de sucesso de 54,4% em usuários que se recuperaram de um estado "bloqueado anteriormente" quando o elemento foi apresentado.

Redefinição do design

Embora o conceito tenha sido bem-sucedido, a implementação precisou ser refinada. O feedback dos fornecedores de navegadores, incluindo Apple (Safari/WebKit) e Mozilla (Firefox), indicou que um elemento "único" introduziu uma complexidade significativa em relação a comportamentos de recursos exclusivos.

Como consequência, passamos de um controle de permissão genérico para elementos direcionados e específicos de recursos (consulte a discussão do WICG). O elemento <geolocation> é o primeiro desses controles especializados a ser lançado. Além disso, estamos desenvolvendo um elemento <usermedia> dedicado (para acesso à câmera e ao microfone), que tem um teste de origem separado.

Ao contrário da proposta original, que se concentrava no gerenciamento do estado de permissão (ou seja, permitir ou negar), esses novos elementos funcionam como mediadores de dados, substituindo efetivamente a necessidade de chamar as APIs JavaScript diretamente na maioria dos casos de uso.

Por que usar o elemento <geolocation>?

No momento, os fluxos de geolocalização dependem da API Geolocation, que aciona solicitações de permissão que podem interromper os usuários se forem disparadas fora de contexto ou até mesmo no carregamento da página. A dependência dessas solicitações imperativas está se tornando menos viável devido às intervenções do navegador. Por exemplo, o Chrome bloqueia solicitações de permissão se um usuário dispensou o aviso três vezes, aplicando um bloqueio temporário que dura inicialmente uma semana. Isso significa que o código legado que tenta acionar um aviso pode falhar silenciosamente, deixando o usuário com uma experiência quebrada e sem uma maneira clara de ativar o recurso. Além disso, os comandos padrão geralmente não têm contexto. Se um pedido aparecer inesperadamente, os usuários poderão bloqueá-lo por reflexo ou acidentalmente, sem saber que essa decisão cria um bloqueio permanente que é difícil de reverter. Essa lacuna de contexto, e não o recurso em si, é um dos principais motivos das altas taxas de recusa.

O elemento <geolocation> resolve o problema de lacuna de contexto ao garantir que as solicitações sejam iniciadas estritamente pelo usuário. Esse modelo oferece três vantagens distintas:

• Objetivo e tempo claros:ao clicar em um botão usar localização, o usuário sinaliza explicitamente a intenção de usar a localização naquele momento específico. Isso indica que eles entendem o valor e querem usar ativamente a localização, transformando um possível bloqueio em uma interação bem-sucedida.
• Recuperação simplificada:se um usuário bloqueou o acesso à localização ao navegar em um site (talvez por acidente ou falta de contexto), clicar no elemento aciona um fluxo de recuperação especializado. Isso ajuda a reativar a localização no momento em que realmente querem usar esse recurso, sem a dificuldade de navegar pelas configurações do site no navegador.
• Atualização automática:se a permissão já tiver sido concedida, clicar no elemento vai funcionar como um botão de atualização, buscando novos dados imediatamente sem solicitar novamente.

Implementação

A integração do elemento exige muito menos código clichê do que a API JavaScript. Em vez de gerenciar callbacks e estados de erro manualmente, os desenvolvedores podem adicionar a tag à página e detectar o evento onlocation.

<geolocation
  onlocation="handleLocation(event)"
  autolocate
  accuracymode="precise">
</geolocation>

function handleLocation(event) {
  // Directly access the GeolocationPosition object on the element
  if (event.target.position) {
    const { latitude, longitude } = event.target.position.coords;
    console.log("Location retrieved:", latitude, longitude);
  } else if (event.target.error) {
    console.error("Error:", event.target.error.message);
  }
}

Principais atributos e propriedades

• autolocate: tenta recuperar automaticamente a localização quando o elemento é carregado, mas apenas se o status de permissão atual já permitir (evitando solicitações inesperadas).
• accuracymode: aceita um valor de "precise" ou "approximate", correspondente à opção padrão enableHighAccuracy.
• watch: muda o comportamento para corresponder a watchPosition(), disparando eventos continuamente à medida que o usuário se move.
• position: uma propriedade somente leitura no elemento DOM que retorna o objeto GeolocationPosition assim que estiver disponível.
• error: uma propriedade somente leitura que retorna um GeolocationPositionError se a solicitação falhar.

Restrições de estilo

Para garantir a confiança do usuário e evitar padrões de design enganosos, o elemento <geolocation> aplica restrições de estilo específicas semelhantes ao experimento anterior do elemento <permission>. É possível personalizar o botão para corresponder ao tema do site, mas o navegador impõe várias restrições:

• Legibilidade:as cores do texto e do plano de fundo são verificadas para garantir contraste suficiente (normalmente uma proporção de pelo menos 3:1) e que a solicitação de permissão seja sempre legível. Além disso, o canal alfa (opacidade) precisa ser definido como 1 para evitar que o elemento fique enganosamente transparente.
• Dimensionamento e espaçamento:o elemento impõe limites mínimos e máximos para largura, altura e tamanho da fonte. Margens negativas ou deslocamentos de contorno são desativados para evitar que o elemento seja visualmente obscurecido ou se sobreponha a outro conteúdo de forma enganosa.
• Integridade visual:os efeitos de distorção são limitados. Por exemplo, a transformação só aceita traduções 2D e escalonamento proporcional.
• Pseudoclasses CSS:o elemento oferece suporte a estilos baseados em estado, como :granted (quando a permissão está ativa).

Estratégia de aprimoramento progressivo

Entendemos que a padronização de novos elementos HTML é um processo gradual. No entanto, os desenvolvedores podem adotar o elemento <geolocation> hoje sem quebrar a compatibilidade para usuários em outros navegadores.

O elemento foi projetado para degradar suavemente. Navegadores que não são compatíveis com o elemento <geolocation> o tratam como um [HTMLUnknownElement](https://developer.mozilla.org/docs/Web/API/HTMLUnknownElement). É importante lembrar que, se o navegador for compatível com o elemento, ele não vai renderizar os filhos. Isso permite escrever o HTML de maneira limpa para navegadores compatíveis e não compatíveis.

Padrão de fallback personalizado

Se você quiser controlar totalmente a experiência de substituição, use elementos filhos, como um botão que você conecta à API Geolocation JavaScript normal.

<geolocation onlocation="updateMap()">
  <!-- Fallback contents if the element is not supported -->
  <button onclick="navigator.geolocation.getCurrentPosition(updateMap)">
    Use my location
  </button>
</geolocation>

Polyfill

Como alternativa, é possível instalar um polyfill do npm que substitui de forma transparente e automática todas as ocorrências de <geolocation> por um elemento personalizado <geo-location> (observe o traço) com suporte da API JavaScript Geolocation regular. Se o navegador for compatível com o elemento <geolocation>, o polyfill não fará nada. Confira esta demonstração que mostra o polyfill em ação. O código-fonte está no GitHub.

if (!('HTMLGeolocationElement' in window)) {
  await import('https://unpkg.com/geolocation-element-polyfill/index.js');
}

<geolocation onlocation="updateMap()"></geolocation>

Detecção de recursos

Para uma lógica mais complexa, detecte o suporte de maneira programática usando a interface:

if ('HTMLGeolocationElement' in window) {
  // Use modern <geolocation> element logic
} else {
  // Fallback to legacy navigator.geolocation API
}

Conclusão

Estamos animados para ver como os desenvolvedores vão implementar cenários de nova tentativa de localização mais eficientes usando o novo elemento HTML <geolocation>. Ele representa uma mudança para elementos específicos de recursos que são adaptados à forma como os usuários usam a Web hoje.

Para outros casos de uso de permissão, a partir do Chrome 144, você pode participar do teste de origem do elemento HTML <usermedia>, trazendo os mesmos benefícios ergonômicos para a câmera e o microfone.

Links relacionados

• O elemento <geolocation> no Status da plataforma do Chrome
• Explicação sobre o elemento HTML de geolocalização
• Página de demonstração
• Posição da Mozilla sobre padrões
• WebKit Standards Position (em inglês)

Agradecimentos

Este documento foi revisado por Andy Paicu, Gilberto Cocchi e Rachel Andrew.