Diretivas no Vue 3: nativas e personalizadas

Diretivas são atributos especiais de template, sempre com o prefixo v-, que ligam o HTML ao estado e ao comportamento da sua aplicação. Aqui estão as diretivas nativas do Vue 3, a sintaxe com argumentos e modificadores, a escolha entre v-if e v-show e o passo a passo para criar a sua própria diretiva, inclusive no Nuxt 4, onde é preciso cuidar da renderização no servidor.
Os exemplos usam Vue 3.5 com <script setup>.
O que são diretivas no Vue?
Uma diretiva recebe uma expressão JavaScript como valor e aplica um comportamento reativo ao elemento onde está. Quando o valor muda, o Vue atualiza o elemento. Elas controlam atributos, eventos, repetição de listas e quais elementos aparecem na tela.
Existem dois grupos. As diretivas nativas, como v-if e v-for, já vêm com o Vue. As diretivas personalizadas são criadas por você para os casos em que é preciso mexer diretamente no elemento do DOM.
Como funciona a sintaxe das diretivas?
Uma diretiva tem até quatro partes: o nome, um argumento opcional depois de dois pontos, modificadores opcionais separados por ponto e o valor. As duas primeiras linhas abaixo são equivalentes, porque : é a abreviação de v-bind: e @ é a abreviação de v-on::
<template>
<a v-bind:href="url">Visite nosso site</a>
<a :href="url">Visite nosso site</a>
<button @click="salvar">Salvar</button>
<!-- argumento dinâmico: o nome do atributo vem de uma variável -->
<a :[atributo]="url">Visite nosso site</a>
<!-- modificador: chama event.preventDefault() no envio -->
<form @submit.prevent="enviar">...</form>
</template>
Nos projetos Vue, a forma curta é a mais comum. Os modificadores mudam o comportamento da diretiva, e cada diretiva tem os seus. .prevent e .stop valem para v-on, enquanto .lazy, .number e .trim valem para v-model.
Quais são as principais diretivas nativas?
v-bind: atributos dinâmicos
O v-bind liga o valor de uma variável a um atributo do elemento. Se a variável mudar, o atributo muda junto:
<template>
<a :href="url">Visite nosso site</a>
</template>
<script setup>
import { ref } from "vue";
const url = ref("https://codigoaoponto.com/");
</script>
v-model: vinculação bidirecional
O v-model sincroniza um campo de formulário com uma variável nos dois sentidos. Digitar no campo atualiza a variável, e alterar a variável atualiza o campo:
<template>
<input v-model="nome" type="text" />
<div>Olá! Meu nome é {{ nome }}</div>
</template>
<script setup>
import { ref } from "vue";
const nome = ref("Teste");
</script>
Em componentes, o v-model depende de uma propriedade e de um evento compatíveis. No Vue 3 você pode ter mais de um v-model no mesmo componente, cada um com um nome. A partir do Vue 3.4, a macro defineModel cria esse par para você.
v-on: eventos
O v-on liga um evento do navegador a uma função:
<template>
<input v-model="nome" type="text" />
<button @click="resetar">Resetar</button>
</template>
<script setup>
import { ref } from "vue";
const nome = ref("Teste");
function resetar() {
nome.value = "";
}
</script>
v-for: listas e a key
O v-for cria um elemento para cada item de um array ou objeto. Ele precisa de uma :key com um valor único e estável de cada item, para o Vue saber qual elemento corresponde a qual dado:
<template>
<ul>
<li v-for="tarefa in tarefas" :key="tarefa.id">
{{ tarefa.titulo }}
</li>
</ul>
</template>
<script setup>
const tarefas = [
{ id: 101, titulo: "Revisar a documentação" },
{ id: 102, titulo: "Atualizar as dependências" },
{ id: 103, titulo: "Publicar o artigo" }
];
</script>
O índice do array só serve de key em listas estáticas. Se a lista pode ser reordenada, filtrada ou receber e perder itens, o índice faz o Vue reaproveitar o elemento errado. O problema aparece principalmente quando cada linha tem um campo de texto, um componente ou uma animação com estado próprio.
v-if, v-else-if e v-else: renderização condicional
O v-if inclui o elemento só quando a condição é verdadeira. O v-else-if e o v-else encadeiam as alternativas:
<template>
<input v-model="nome" type="text" />
<div v-if="nome.length > 10">Seu nome é muito longo!</div>
<div v-else-if="nome">Olá! Meu nome é {{ nome }}</div>
<div v-else>Por favor, digite seu nome.</div>
</template>
<script setup>
import { ref } from "vue";
const nome = ref("");
</script>
v-show: visibilidade
O v-show mantém o elemento no DOM e alterna a propriedade CSS display:
<template>
<div v-show="nome.length > 10">Seu nome é muito longo!</div>
</template>
v-html e v-text
O v-text define o texto do elemento, como a interpolação {{ }} faz. O v-html insere a string como HTML.
Nunca use
v-htmlcom conteúdo vindo do usuário ou de fonte externa sem sanitizar antes. Um HTML malicioso nessa string é uma falha de XSS. A interpolação comum trata tudo como texto e é a opção segura.
Outras diretivas
O Vue tem mais cinco diretivas que aparecem menos no dia a dia:
v-slotrecebe o conteúdo de slots nomeados e com escopo.v-oncerenderiza o elemento uma vez e ignora as atualizações seguintes.v-prepula a compilação do elemento e dos filhos, útil para mostrar{{ }}literalmente.v-cloakesconde o template até ele ser compilado, em projetos sem etapa de build.v-memoevita reprocessar um trecho do template enquanto os valores listados não mudarem.
v-if ou v-show: qual escolher?
Os dois escondem um elemento, mas por caminhos diferentes. O v-if só renderiza o bloco quando a condição é verdadeira e, ao mudar, destrói e recria o bloco com seus componentes e listeners. O v-show renderiza o elemento sempre e só alterna o display.
A orientação da documentação é usar v-show quando você alterna algo com muita frequência, porque o custo de alternar é menor. Use v-if quando a condição raramente muda em tempo de execução, porque assim o bloco nem é criado enquanto não for necessário.
O v-show tem duas limitações: não funciona em <template> e não combina com v-else. Para esconder vários elementos de uma vez, use v-if em um <template>.
Como criar uma diretiva personalizada no Vue 3?
Uma diretiva personalizada é um objeto com funções de ciclo de vida que recebem o elemento do DOM. A documentação do Vue recomenda preferir o template declarativo e reservar diretivas para quando você precisa de acesso direto ao elemento.
Diretiva local com script setup
Dentro de um <script setup>, qualquer variável em camelCase que comece com v vira uma diretiva. A variável vFocus fica disponível no template como v-focus:
<script setup>
const vFocus = {
mounted: (el) => el.focus()
};
</script>
<template>
<input v-focus />
</template>
Aqui o hook mounted roda quando o elemento é inserido no DOM e foca o campo.
Registro global com app.directive
Se várias partes da aplicação usam a diretiva, escreva-a em um arquivo e registre uma vez com app.directive:
// directives/focus.ts
import type { Directive } from "vue";
export const vFocus: Directive<HTMLElement> = {
mounted: (el) => el.focus()
};
// main.ts
import { createApp } from "vue";
import App from "./App.vue";
import { vFocus } from "./directives/focus";
const app = createApp(App);
app.directive("focus", vFocus);
app.mount("#app");
Hooks do ciclo de vida
Uma diretiva pode implementar estes hooks, listados na ordem em que acontecem:
created: antes de os atributos e listeners do elemento serem aplicados.beforeMount: antes de o elemento ser inserido no DOM.mounted: depois de o componente pai e todos os filhos serem montados.beforeUpdate: antes de o componente pai ser atualizado.updated: depois de o componente pai e os filhos serem atualizados.beforeUnmount: antes de o componente pai ser desmontado.unmounted: depois de o componente pai ser desmontado.
Todos recebem el (o elemento), binding e vnode. Os hooks de atualização recebem também prevVnode. O objeto binding traz o value passado à diretiva, o oldValue (só em beforeUpdate e updated), o arg, os modifiers, a instance do componente e a definição da própria diretiva em dir. Trate tudo isso, menos o el, como somente leitura.
Valor, argumento e modificadores
Quando o mesmo comportamento deve rodar na montagem e em cada atualização, escreva a diretiva como uma função. Ela é chamada em mounted e em updated:
// directives/destaque.ts
import type { Directive } from "vue";
// uso: <p v-destaque:background.suave="'#fff3b0'">Texto</p>
export const vDestaque: Directive<HTMLElement, string> = (el, binding) => {
el.style.setProperty(binding.arg ?? "color", binding.value);
if (binding.modifiers.suave) {
el.style.transition = "all 0.3s";
}
};
O arg é background, o modificador suave aparece em binding.modifiers e o value é a cor. Quando a diretiva precisa de várias opções, o valor pode ser um objeto: v-destaque="{ cor: 'white', duracao: 300 }".
Limpando listeners
Toda diretiva que registra um listener em document ou window, um observer ou um timer precisa desfazer isso quando o elemento sai da tela. O exemplo clássico é fechar um menu ao clicar fora dele:
// directives/clickOutside.ts
import type { Directive } from "vue";
type ElementoComListener = HTMLElement & {
_aoClicarFora?: (event: MouseEvent) => void;
};
export const vClickOutside: Directive<ElementoComListener, () => void> = {
mounted(el, binding) {
el._aoClicarFora = (event) => {
if (!el.contains(event.target as Node)) {
binding.value();
}
};
document.addEventListener("click", el._aoClicarFora);
},
unmounted(el) {
if (el._aoClicarFora) {
document.removeEventListener("click", el._aoClicarFora);
delete el._aoClicarFora;
}
}
};
A função é guardada no elemento para que o unmounted remova exatamente a mesma referência que o mounted registrou. Sem isso, o listener fica vivo depois de o elemento sumir. Este exemplo lê binding.value só na montagem. Se a função passada puder mudar, atualize a referência também no hook updated.
Diretiva, composable ou componente?
A diretiva serve quando a lógica precisa tocar um elemento específico, como focar um campo. Se a lógica tem estado ou funciona sem estar presa a um elemento, como um debounce reutilizável, um composable resolve melhor. Quando existe estrutura visual, como um tooltip acessível ou um menu com teclado e submenus, o certo é um componente.
Um tooltip bom exige posicionamento, foco, teclado e a tecla Esc. Uma diretiva que tenta cobrir tudo isso costuma acabar mais complicada que o componente equivalente.
Como usar diretivas personalizadas no Nuxt 4?
No Nuxt, uma diretiva global é registrada em um plugin da pasta app/plugins/, usando nuxtApp.vueApp.directive. Como o Nuxt renderiza a página no servidor, há uma regra a mais: durante o SSR, o Vue ignora os hooks de uma diretiva, porque eles manipulam o DOM e o servidor não tem DOM. Se a diretiva precisa colocar algum atributo no HTML gerado, use o hook getSSRProps, que devolve as props a renderizar:
// app/plugins/directives.ts
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.directive("focus", {
mounted: (el: HTMLElement) => el.focus(),
getSSRProps: () => ({ autofocus: true })
});
});
Com esse plugin, <input v-focus /> sai do servidor como <input autofocus>. Sem o getSSRProps, sairia um <input> sem nada, e o foco só viria depois da hidratação.
A documentação do Nuxt pede que a diretiva seja registrada no cliente e no servidor, a menos que ela só seja usada em um dos lados. Para uma diretiva exclusiva do navegador, como o v-click-outside, crie o plugin com sufixo .client e um plugin .server com uma diretiva vazia, só para o Vue reconhecer o nome:
// app/plugins/click-outside.client.ts
import { vClickOutside } from "~/directives/clickOutside";
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.directive("click-outside", vClickOutside);
});
// app/plugins/click-outside.server.ts
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.directive("click-outside", {});
});
O que muda das diretivas do Vue 2 para o Vue 3?
Muitos tutoriais antigos ainda usam os hooks do Vue 2, e eles não funcionam no Vue 3. Veja a correspondência:
bindviroubeforeMount.insertedviroumounted.componentUpdatedvirouupdated.unbindvirouunmounted.updatefoi removido, porque era redundante comupdated.created,beforeUpdateebeforeUnmountsão novos.
O objeto binding também perdeu a string expression, e a instância do componente deixou de vir de vnode.context e passou para binding.instance.
Quais são os erros mais comuns com diretivas?
- Usar
v-ifev-forno mesmo elemento. Ov-ifé avaliado primeiro, e a documentação não recomenda a combinação. Filtre a lista em uma propriedade computada ou separe em dois elementos. - Usar o índice como
keyem listas que mudam. - Aplicar
v-htmla texto que veio do usuário. - Registrar um listener ou timer sem removê-lo em
unmounted. - Aplicar uma diretiva personalizada em um componente com mais de um elemento raiz. A diretiva é ignorada e o Vue emite um aviso. A documentação não recomenda usar diretivas personalizadas em componentes.
- Contar com a manipulação do DOM durante o SSR.
- Criar uma diretiva para algo que seria mais simples como componente.
Perguntas frequentes
O que são diretivas no Vue?
São atributos especiais de template, iniciados por v-, que aplicam comportamento reativo ao elemento, como alterar atributos, ouvir eventos, repetir elementos ou controlar a renderização.
Qual é a diferença entre v-if e v-show?
O v-if monta e desmonta o bloco conforme a condição. O v-show mantém o elemento no DOM e alterna o display. Use v-show para alternâncias frequentes e v-if quando a condição muda pouco.
Posso usar o índice do array como key no v-for?
Só em listas estáticas, que nunca mudam de ordem nem de tamanho. Em listas que mudam, use um id estável do próprio item.
Como criar uma diretiva personalizada com script setup?
Declare uma variável em camelCase iniciada por v, como vFocus, e use no template como v-focus. O Vue trata isso como registro local.
Quando usar uma diretiva em vez de um composable?
Use a diretiva quando a lógica precisa manipular diretamente um elemento do DOM. Se a lógica tem estado ou não depende de um elemento específico, prefira um composable.
Diretivas personalizadas funcionam no SSR do Nuxt?
Os hooks que mexem no DOM não rodam no servidor. Para gerar atributos no HTML do servidor, implemente getSSRProps. Para uma diretiva que só faz sentido no navegador, registre-a em um plugin .client e crie um stub .server.
Conclusão
Para escolher entre as ferramentas, comece pelo elemento: se a lógica precisa tocar nele, use uma diretiva; se tem estado e pode ser reaproveitada, use um composable; se tem estrutura visual, use um componente. Dentro das nativas, troque o índice por um id estável no v-for e decida entre v-if e v-show pela frequência da alternância.
Para se aprofundar, leia as páginas da documentação sobre diretivas personalizadas, renderização condicional, renderização de listas e plugins do Nuxt.

