CSS :scope Pseudo Classe
A pseudo-classe CSS :scope representa elementos de escopo. Leia sobre ela e pratique com exemplos.
A pseudo-classe CSS :scope corresponde ao elemento contra o qual um seletor está sendo resolvido — seu elemento de referência. Em consultas DOM simples, esse elemento de referência é o elemento sobre o qual você chama o método de consulta; dentro de um Shadow DOM, é a raiz da sombra.
Esta página explica o que "escopo" significa para um seletor, por que :scope é principalmente uma ferramenta JavaScript em vez de uma ferramenta de folha de estilos, os dois principais locais onde ela muda o comportamento e os cuidados a observar.
O que é o elemento de referência
Todo seletor é correspondido em relação a algum elemento. Quando você escreve CSS em uma folha de estilos, o elemento de referência é a raiz do documento, portanto :scope equivale a :root e raramente é útil por si só.
:scope se torna significativo quando o elemento de referência não é a raiz — mais importante quando você consulta o DOM a partir do JavaScript:
element.querySelector(selector)eelement.querySelectorAll(selector)resolvem o seletor em relação aelement. Aqui:scoperefere-se ao próprioelement.- Os métodos de consulta de um
ShadowRootusam a raiz da sombra como elemento de referência.
Sem :scope, um seletor passado para element.querySelector() ainda é correspondido em relação a toda a subárvore, sem estar ancorado a element. Isso surpreende muitos desenvolvedores — veja o cuidado abaixo.
Por que usá-lo
O principal motivo para usar :scope é ancorar um seletor ao elemento que você está consultando, para que você possa corresponder filhos diretos ou expressar "relativo a este ponto":
// Match only sections that are direct children of container.
container.querySelectorAll(':scope > section');:scope é significativo dentro dos métodos de consulta listados acima (querySelector, querySelectorAll e a verificação ao vivo Element.matches()). Não tem efeito especial em closest() ou em regras comuns de folha de estilos.
Nota: o antigo atributo <style scoped>, que antes permitia que um bloco <style> se aplicasse apenas dentro do seu elemento pai, foi removido dos navegadores. O escopo de estilos hoje é feito com Shadow DOM (ou ferramentas de build), e :scope sobrevive como o auxiliar de consulta DOM.
Versão
Sintaxe
Em uma folha de estilos, a sintaxe é a mesma que qualquer outra pseudo-classe:
:scope {
/* declarations — equivalent to :root in a normal stylesheet */
}Em JavaScript, é passado dentro da string do seletor:
element.querySelectorAll(':scope > .child');Exemplo: ancorando uma consulta ao seu elemento
No exemplo abaixo, container.querySelector(':scope > section') seleciona apenas o <section> que é filho direto de .container. A seção correspondida é recolorida para confirmar que a consulta a encontrou.
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
<style>
.container {
margin: 40px auto;
max-width: 700px;
background-color: #eeeeee;
padding: 20px;
box-shadow: 0 0 4px rgba(0, 0, 0, 0.25);
}
section {
padding: 30px;
}
</style>
</head>
<body>
<h2>:scope selector example</h2>
<div class="container">
<section>
<p>
Inside the scope.
</p>
</section>
</div>
<script>
const container = document.querySelector('.container');
const scopeElement = container.querySelector(':scope > section');
scopeElement.style.backgroundColor = '#1c87c9';
scopeElement.style.color = '#fff';
</script>
</body>
</html>Armadilha comum: selecionando filhos diretos
O motivo mais comum para usar :scope é selecionar os filhos imediatos do elemento que você está consultando. Um combinador como > .x não pode estar sozinho — element.querySelector('> .x') lança um SyntaxError. Você precisa de um lado esquerdo, e :scope o fornece:
<ul id="list">
<li>A</li>
<li>
<ul>
<li>B (nested)</li>
</ul>
</li>
</ul>const list = document.getElementById('list');
// SyntaxError — "> li" is not a complete selector:
// list.querySelectorAll('> li');
// Correct: only the direct <li> children of #list (A and the one wrapping the nested list),
// NOT "B (nested)".
list.querySelectorAll(':scope > li');Sem :scope, list.querySelectorAll('li') também retornaria o item B aninhado, pois um seletor descendente simples alcança toda a subárvore. :scope > é a forma idiomática de dizer "filhos diretos do elemento que estou consultando".
Suporte nos navegadores
:scope é suportado em todos os navegadores modernos para os métodos de consulta DOM. Não tem efeito como regra de estilo em uma folha de estilos normal além de se comportar como :root.
Capítulos relacionados
- CSS Selectors — a referência completa de seletores.
- CSS Selector — conceitos básicos de sintaxe de seletores.