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 prompts de permissão acionados 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 blocos silenciosos).

Esse lançamento é o 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 o histórico do desenvolvimento dele e os dados que impulsionaram o design.

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

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

Validação do conceito

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

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

• O Zoom informou uma diminuição de 46,9% nos erros de captura de câmera ou microfone (como bloqueadores no nível do sistema) usando 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.
• A ZapImóveis observou uma taxa de sucesso de 54,4% nos usuários que se recuperaram de um estado "bloqueado anteriormente" quando apresentados ao elemento.

Redefinição do design

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

Consequentemente, fizemos a transição de um controle de permissão genérico para elementos específicos de capacidade direcionados, (consulte a discussão do WICG). O <geolocation> elemento é o primeiro desses controles especializados a ser lançado. Depois disso, também estamos desenvolvendo um elemento <usermedia> dedicado (para acesso à câmera e ao microfone), que tem o próprio 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 para a maioria dos casos de uso.

Por que usar o <geolocation> elemento?

Atualmente, os fluxos de geolocalização dependem da API Geolocation, que aciona prompts de permissão que podem interromper os usuários se forem disparados fora do contexto ou até mesmo no carregamento da página. É importante ressaltar que a dependência desses prompts imperativos está se tornando menos viável devido às intervenções do navegador. Por exemplo, o Chrome bloqueia ativamente as solicitações de permissão se um usuário tiver dispensado o prompt três vezes, aplicando um bloco silencioso temporário que dura inicialmente uma semana. Isso significa que o código legado que tenta acionar um prompt pode falhar silenciosamente, deixando o usuário com uma experiência ruim e sem uma maneira clara de ativar o recurso. Além disso, os prompts padrão geralmente não têm contexto. Se um prompt aparecer inesperadamente, os usuários poderão bloqueá-lo reflexivamente 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 fatores de altas taxas de negação.

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

• Intenção e tempo claros:ao clicar em um botão usar local, o usuário sinaliza explicitamente a intenção de usar o local naquele momento específico. Isso indica que eles entendem o valor e querem usar o local ativamente, transformando um possível bloqueio em uma interação bem-sucedida.
• Recuperação simplificada:se um usuário bloqueou o acesso ao local 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 o local no momento em que ele realmente quer usar o local, sem a dificuldade de navegar pelas configurações do site do navegador.
• Atualização automática:se a permissão já estiver 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 boilerplate 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 o local quando o elemento é carregado, mas somente se o status de permissão atual já permitir (evitando prompts inesperados).
• accuracymode: aceita um valor de "precise" ou "approximate", correspondente à opção enableHighAccuracy padrão.
• 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 quando 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 <geolocation> elemento aplica restrições de estilo específicas semelhantes ao experimento anterior do <permission> elemento. Embora seja possível personalizar o botão para corresponder ao tema do site, o navegador aplica várias proteçõ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) para garantir 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 seja enganosamente transparente.
• Dimensionamento e espaçamento:o elemento aplica 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 sobreposto a outro conteúdo de forma enganosa.
• Integridade visual:os efeitos de distorção são limitados. Por exemplo, a transformação oferece suporte apenas a 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 <geolocation> elemento hoje sem quebrar a compatibilidade para usuários em outros navegadores.

O elemento foi projetado para degradar normalmente. Os navegadores que não oferecem suporte ao <geolocation> elemento vão tratá-lo como um HTMLUnknownElement. É importante ressaltar que, se o navegador oferecer suporte ao elemento, ele não vai renderizar os filhos. Isso permite escrever o HTML de forma limpa para navegadores com e sem suporte.

Padrão de fallback personalizado

Se você quiser controlar totalmente a experiência de fallback, 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>

Teste como o comportamento funciona com um exemplo básico.

Fibra de poliéster

Como alternativa, você pode 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 Geolocation JavaScript normal. Se o navegador oferecer suporte ao elemento <geolocation>, o polyfill não fará nada. Confira esta demonstração de polyfill 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, você pode detectar programaticamente o suporte 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 <geolocation> elemento HTML. Ele representa uma mudança em direção a elementos específicos de capacidade 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> trial, trazendo esses mesmos benefícios ergonômicos para a câmera e o microfone.

Links relacionados

• O elemento <geolocation> no Status da plataforma Chrome
• Vídeo explicativo do elemento HTML de geolocalização
• Página de demonstração
• Posição de padrões da Mozilla
• Posição de padrões do WebKit

Agradecimentos

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