Primeiros Passos
Hello World e Comentários
Um app Vue 3 começa com createApp() e mount() num elemento do DOM. A interpolação usa chaves duplas {{ }} para renderizar dados reativos. Comentários HTML aparecem no DOM renderizado; para comentários que não vazem, use /* */ dentro de blocos <script>.
<!-- index.html -->
<div id="app">
<p>{{ message }}</p>
<!-- This is an HTML comment, visible in DOM -->
</div>
<script type="module">
import { createApp } from 'vue'
createApp({
data() {
return { message: 'Hello Vue 3!' }
}
}).mount('#app')
</script>Estrutura de SFC (Componente de Arquivo Único)
Um SFC agrupa template, script e style num único arquivo .vue. <script setup> é a sintaxe recomendada para a Composition API — concisa e sem boilerplate. Estilos scoped se aplicam só ao componente atual, prevenindo vazamento. Cada SFC compila para um módulo JavaScript.
<template>
<button @click="count++">Count: {{ count }}</button>
</template>
<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>
<style scoped>
button { color: #42B883; }
</style>Instância do App e Mount
createApp retorna uma instância de aplicação com escopo nela própria — sem estado Vue global, então você pode montar múltiplos apps independentes numa página. Registre plugins, forneça valores globais e defina a config antes de chamar mount(). Depois do mount, mudanças de config posteriores não terão efeito.
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
// global config / plugins before mounting
app.config.errorHandler = (err) => console.error(err)
app.provide('apiKey', '12345')
app.mount('#app')Scaffolding de Projeto (Vite)
npm create vue@latest é a ferramenta oficial de scaffolding, oferecendo setup opcional de TypeScript, Router, Pinia e Vitest. Usa Vite para início instantâneo do dev server e HMR. create-vite é a ferramenta de nível mais baixo, se você quiser um template mínimo sem as opiniões do Vue.
# scaffold a new Vue project with Vite
npm create vue@latest my-app
cd my-app
npm install
npm run dev # start dev server (HMR)
npm run build # production build to /dist
# or with create-vite directly
npm create vite@latest my-app -- --template vue-tsdefineOptions e defineProps
defineProps, defineEmits e defineOptions são macros de tempo de compilação — não precisam ser importados. defineProps declara o contrato de props do componente com validação em runtime. defineOptions permite definir name, inheritAttrs e outras opções não expressáveis diretamente em <script setup>.
<script setup>
// declare props with types and defaults
const props = defineProps({
title: String,
count: { type: Number, default: 0 }
})
// declare emits
const emit = defineEmits(['update', 'delete'])
// additional non-reactive options
defineOptions({ name: 'MyButton', inheritAttrs: false })
</script>Sintaxe de Template
Interpolação de Texto
{{ }} renderiza texto com segurança (HTML escapado). v-once congela um binding após o primeiro render, para conteúdo estático. v-html injeta HTML cru — use só em conteúdo confiável, para evitar XSS. Dentro de {{ }} você pode usar qualquer expressão JavaScript única, mas não instruções como atribuições ou declarações var.
<template>
<p>{{ message }}</p>
<!-- renders the value of message -->
<!-- one-time binding (no updates after render) -->
<span v-once>{{ initialCount }}</span>
<!-- raw HTML (sanitize to avoid XSS!) -->
<div v-html="rawHtmlContent"></div>
<!-- expressions are supported -->
<p>{{ count * 2 }}</p>
<p>{{ isReady ? 'Yes' : 'No' }}</p>
<p>{{ message.split('').reverse().join('') }}</p>
</template>Binding de Atributos
v-bind (abreviação :) vincula atributos de forma reativa. Para class, você pode passar um objeto (chaves truthy se aplicam), array ou string. style aceita um objeto com chaves camelCase ou kebab-case. A sintaxe de argumento dinâmico :[expr] permite que o próprio nome do atributo seja reativo — útil para nomes de eventos ou atributos localizados.
<template>
<!-- bind an attribute -->
<img v-bind:src="imageUrl" />
<img :src="imageUrl" /> <!-- shorthand -->
<!-- bind class -->
<div :class="{ active: isActive, error: hasError }"></div>
<div :class="['btn', isActive && 'active']"></div>
<!-- bind style -->
<div :style="{ color: textColor, fontSize: size + 'px' }"></div>
<!-- dynamic attribute name -->
<button :[eventName]="handler">Click</button>
</template>Atributos Booleanos e Multivalorados
Para atributos booleanos como disabled ou checked, o Vue renderiza o atributo só quando o valor é truthy. class e style são especiais: o Vue mescla valores estáticos e vinculados em vez de substituí-los. Para inputs de formulário, prefira v-model a vincular manualmente :value e @input.
<template>
<!-- boolean attribute: presence depends on value -->
<input :disabled="isDisabled" />
<button :disabled="!canSubmit">Submit</button>
<!-- class merging: bound class merges with static class -->
<div class="card" :class="{ highlighted: isFeatured }"></div>
<!-- style merging: bound style merges with static style -->
<div style="color: red" :style="{ fontSize: '14px' }"></div>
<!-- form attributes: value is bound with v-model instead -->
<input v-model="text" />
</template>Modificadores e Expressões
Modificadores são posfixos indicados por ponto, indicando tratamento especial. Modificadores de evento (.prevent, .stop, .once, .self) embrulham o handler com a função DOM correspondente. Modificadores de tecla (.enter, .esc, .ctrl) filtram eventos por tecla. Modificadores de v-model (.trim, .number, .lazy) transformam o valor de entrada antes da atribuição.
<template>
<!-- .prevent calls event.preventDefault() -->
<form @submit.prevent="onSubmit">...</form>
<!-- .stop calls event.stopPropagation() -->
<button @click.stop="doStuff">Click</button>
<!-- .once runs handler only one time -->
<button @click.once="init">Init</button>
<!-- .trim and .lazy modifiers on v-model -->
<input v-model.trim="email" />
<input v-model.lazy="text" />
<!-- chain multiple modifiers -->
<input @keyup.enter.ctrl="onCombo" />
</template>Template Refs
Template refs dão acesso direto a elementos do DOM. Declare um ref() com o mesmo nome do atributo ref — o Vue atribui o nó do DOM após o mount. Acesse dentro de onMounted (ou depois); antes do mount, o ref é null. Para v-for, o ref vira um array de elementos. Evite recorrer a refs quando fluxos de dados reativos bastariam.
<script setup>
import { ref, onMounted } from 'vue'
// declare a ref matching the template ref attribute
const inputEl = ref(null)
onMounted(() => {
// access the DOM node after mount
inputEl.value.focus()
})
</script>
<template>
<input ref="inputEl" />
</template>Diretivas
v-if / v-else-if / v-else
v-if renderiza elementos condicionalmente — eles são adicionados/removidos do DOM. v-else-if e v-else encadeiam com um v-if precedente. Envolva múltiplos elementos num <template v-if> quando não quiser um elemento wrapper extra. v-if tem custo de alternância maior (criação de DOM), mas custo inicial menor que v-show quando a condição é falsa.
<template>
<div v-if="type === 'A'">Type A</div>
<div v-else-if="type === 'B'">Type B</div>
<div v-else-if="type === 'C'">Type C</div>
<div v-else>Unknown type</div>
<!-- use <template> for invisible wrapper -->
<template v-if="showHeader">
<h1>Title</h1>
<p>Subtitle</p>
</template>
</template>v-show vs v-if
Use v-if quando a condição raramente muda — elementos são destruídos e recriados, economizando custo de render quando ocultos. Use v-show para elementos alternados com frequência (tabs, dropdowns) — o elemento permanece no DOM e só display:none alterna, tornando a alternância barata. v-show não funciona com <template> ou v-else.
<template>
<!-- v-if removes from DOM when false -->
<p v-if="isVisible">I'm created/destroyed</p>
<!-- v-show just toggles display:none -->
<p v-show="isVisible">I'm always in DOM, just hidden</p>
</template>
<script setup>
import { ref } from 'vue'
const isVisible = ref(true)
</script>v-for e :key
v-for itera arrays, objetos ou um intervalo numérico. O atributo :key é OBRIGATÓRIO para a identidade de rastreamento — permite que o Vue reutilize nós do DOM eficientemente durante reordenações. Use um id único estável como key; nunca o índice do array (quebra quando itens se movem). v-for tem prioridade maior que v-if no mesmo elemento — evite usar ambos num único elemento.
<template>
<!-- iterate over array -->
<li v-for="item in items" :key="item.id">
{{ item.name }}
</li>
<!-- iterate with index -->
<li v-for="(item, index) in items" :key="item.id">
{{ index }}: {{ item.name }}
</li>
<!-- iterate over object -->
<li v-for="(value, key) in user" :key="key">
{{ key }}: {{ value }}
</li>
<!-- range (1 to n) -->
<span v-for="n in 10" :key="n">{{ n }}</span>
</template>Bindings de v-model
v-model é binding bidirecional para inputs de formulário: sincroniza o valor da entrada com o estado reativo. Um checkbox único vincula a um booleano; múltiplos checkboxes com o mesmo v-model vinculam a um array de valores marcados. Use modificadores: .lazy (sincroniza no change em vez de input), .number (converte para número), .trim (remove espaços).
<template>
<!-- text input -->
<input v-model="text" />
<!-- multi-line textarea -->
<textarea v-model="message"></textarea>
<!-- checkbox (single = boolean, multiple = array) -->
<input type="checkbox" v-model="isChecked" />
<input type="checkbox" value="apple" v-model="fruits" />
<input type="checkbox" value="banana" v-model="fruits" />
<!-- radio -->
<input type="radio" value="A" v-model="picked" />
<!-- select -->
<select v-model="selected">
<option value="a">A</option>
<option value="b">B</option>
</select>
</template>Diretivas Personalizadas
Diretivas personalizadas permitem manipular diretamente elementos do DOM. Em <script setup>, qualquer variável nomeada vAlgo (camelCase) fica automaticamente disponível como v-algo no template. O objeto da diretiva tem hooks de ciclo de vida: mounted, updated, unmounted etc. Prefira componentes a diretivas quando precisar de reatividade — diretivas são para trabalho DOM de baixo nível, como foco, tooltips ou arrastar.
<script setup>
// local directive: function form (mounted + updated)
const vFocus = {
mounted: (el) => el.focus()
}
// global registration
// app.directive('focus', { mounted: el => el.focus() })
</script>
<template>
<input v-focus />
</template>Propriedades Computadas
Computed Básico
computed cria um getter em cache que se reavalia só quando suas dependências mudam. Diferente de uma chamada de função, acessos repetidos retornam o valor em cache até uma dependência atualizar. Em <script>, acesse via .value; nos templates, o Vue desembrulha automaticamente. Use computed em vez de funções sempre que o valor depender de estado reativo — é mais rápido e declarativo.
<script setup>
import { ref, computed } from 'vue'
const firstName = ref('John')
const lastName = ref('Doe')
// computed caches based on dependencies
const fullName = computed(() => {
return firstName.value + ' ' + lastName.value
})
// access via .value in script
console.log(fullName.value) // 'John Doe'
</script>
<template>
<!-- use without .value in template -->
<p>{{ fullName }}</p>
</template>Computed Gravável
Por padrão, computed é somente leitura, mas você pode fornecer getter e setter. O setter é invocado quando você atribui a .value. Útil para binding bidirecional em estado derivado, ex.: sincronizar um input de nome completo de volta aos campos nome/sobrenome. Cuidado para evitar loops infinitos — setters não devem definir diretamente as próprias dependências do computed de forma que se reacione.
<script setup>
import { ref, computed } from 'vue'
const firstName = ref('John')
const lastName = ref('Doe')
const fullName = computed({
get() {
return firstName.value + ' ' + lastName.value
},
set(newValue) {
[firstName.value, lastName.value] = newValue.split(' ')
}
})
// assignment triggers the setter
fullName.value = 'Jane Smith'
</script>Computed vs Funções
Propriedades computadas cacheiam o resultado com base nas dependências — só reexecutam quando items muda. Funções reexecutam a cada render, independentemente do que mudou. Use computed para valores derivados de estado reativo; use funções para ações que recebem parâmetros ou têm efeitos colaterais. Computed também torna a intenção mais clara: 'este valor é derivado' vs 'faça isto'.
<script setup>
import { ref, computed } from 'vue'
const items = ref([1, 2, 3, 4, 5])
// computed: cached, re-runs only if items changes
const doubled = computed(() =>
items.value.map(x => x * 2)
)
// method: re-runs on every render
function getDoubled() {
return items.value.map(x => x * 2)
}
</script>
<template>
<!-- cached, no recompute on unrelated re-renders -->
<p>{{ doubled }}</p>
<!-- re-invoked on every render -->
<p>{{ getDoubled() }}</p>
</template>Armadilhas de Computed com Getter
Getters de computed precisam ser puros: sem efeitos colaterais (sem mutações, sem async, sem fetches). Não chame Date.now() nem Math.random() — não são reativos, então o computed não atualizará. Se precisar de efeito colateral, use um watcher. Se precisar de async, computed não aguarda — use watch + um ref, ou setup assíncrono com Suspense.
<script setup>
import { ref, computed } from 'vue'
const date = ref(new Date())
// BAD: non-reactive Date.now() — won't update
const badTime = computed(() => Date.now())
// BAD: side effect inside computed
const count = ref(0)
const bad = computed(() => {
count.value++ // never mutate state in computed!
return count.value
})
// GOOD: pure function of reactive state
const formatted = computed(() =>
date.value.toLocaleDateString()
)
</script>Computed na Options API
Na Options API, declare computed na opção computed. São acessados como this.total (sem .value, sem par ênteses) — o Vue desembrulha automaticamente. Computed gravável usa funções get/set. Propriedades computadas são expostas na instância do componente junto com data e methods, todas acessíveis via this.
<script>
export default {
data() {
return { price: 100, quantity: 2 }
},
computed: {
total() {
return this.price * this.quantity
},
discounted: {
get() { return this.total * 0.9 },
set(v) { this.price = v / 0.9 / this.quantity }
}
},
methods: {
checkout() { console.log(this.total) }
}
}
</script>Watchers
watch Básico
watch roda um callback quando a fonte observada muda. A fonte pode ser um ref, uma propriedade de objeto reativo (via getter) ou um array de fontes. O callback recebe (novoValor, valorAntigo). Use um getter () => x.y para observar propriedades reativas aninhadas. Watchers são para efeitos colaterais (fetch, log, persistir) — não para derivar estado (use computed para isso).
<script setup>
import { ref, watch } from 'vue'
const question = ref('')
// watch a ref
watch(question, (newValue, oldValue) => {
console.log('changed from', oldValue, 'to', newValue)
})
// watch a getter (computed source)
watch(
() => question.value.length,
(newLen) => {
if (newLen > 100) console.warn('Too long!')
}
)
</script>Deep Watch e Immediate
deep: true faz o watch disparar em mudanças de qualquer propriedade aninhada de um objeto — útil, mas caro em estruturas grandes. immediate: true dispara o callback imediatamente no setup (valorAntigo é undefined na primeira chamada). Evite deep watch em objetos enormes — prefira observar um getter específico () => obj.campoEspecifico por melhor desempenho.
<script setup>
import { reactive, watch } from 'vue'
const user = reactive({
name: 'Alice',
address: { city: 'NYC', zip: '10001' }
})
// deep: watch nested property changes
watch(
() => user.address,
(newAddr) => console.log('address changed', newAddr),
{ deep: true }
)
// immediate: run callback right away
watch(
user,
(val) => saveToServer(val),
{ deep: true, immediate: true }
)
</script>watchEffect (Rastreamento Automático)
watchEffect roda o callback imediatamente e rastreia automaticamente quaisquer dependências reativas acessadas dentro dele. Sempre que qualquer dependência rastreada muda, o callback reexecuta. Diferente de watch, você não especifica a fonte — ela é inferida. Use watchEffect quando não precisar do valorAntigo e quiser rastreamento automático de dependências. Útil para configurar assinaturas que leem múltiplas fontes reativas.
<script setup>
import { ref, watchEffect } from 'vue'
const a = ref(1)
const b = ref(2)
// runs immediately and tracks dependencies automatically
watchEffect(() => {
console.log('a + b =', a.value + b.value)
})
// logs: a + b = 3
a.value = 10 // logs: a + b = 12
// stop the watcher
const stop = watchEffect(() => { /* ... */ })
stop() // cleanup
</script>watch vs watchEffect
Escolha watch quando precisar de: valorAntigo, execução preguiçosa (pular a execução inicial) ou observar uma fonte específica explicitamente. Escolha watchEffect quando: quiser execução imediata, não precisar do valorAntigo, ou tiver efeitos colaterais tocando múltiplos valores reativos e quiser rastreamento automático. watch com fonte de array fornece arrays de valores novos/antigos no callback.
<script setup>
import { ref, watch, watchEffect } from 'vue'
const count = ref(0)
// watch: lazy, explicit source, has oldValue
watch(count, (newVal, oldVal) => {
console.log('count changed:', oldVal, '->', newVal)
})
// watchEffect: eager, auto-tracked, no oldValue
watchEffect(() => {
console.log('count is', count.value)
})
// logs immediately: count is 0
// watch multiple sources
const a = ref(1), b = ref(2)
watch([a, b], ([newA, newB], [oldA, oldB]) => {
console.log('a or b changed')
})
</script>Limpeza e Flush de Watchers
O callback onCleanup (3º argumento) registra uma função de limpeza que roda antes da próxima invocação do watcher — perfeito para cancelar requisições em andamento, limpar timers ou cancelar assinaturas. flush: 'post' roda o watcher depois que o Vue atualiza o DOM (útil quando precisa ler o DOM atualizado). 'sync' roda sincronamente na mudança de dependência — raramente necessário e pode causar problemas de desempenho.
<script setup>
import { ref, watch } from 'vue'
const id = ref(1)
// cleanup function: runs before next callback
watch(id, (newId, oldId, onCleanup) => {
const controller = new AbortController()
fetch(`/api/user/${newId}`, { signal: controller.signal })
.then(r => r.json())
// cancel previous request when id changes again
onCleanup(() => controller.abort())
}, { flush: 'post' })
// flush: 'pre' (default) | 'post' (after DOM update) | 'sync'
</script>Renderização Condicional
v-if vs v-show
v-if realmente adiciona/remove elementos do DOM — custo inicial maior, mas custo zero quando oculto. v-show sempre renderiza o elemento e alterna display:none — alternância mais barata, mas o elemento existe mesmo oculto. Use v-if para condicionais que raramente mudam (ou quando elementos ocultos não deveriam existir em absoluto). Use v-show para UI alternada com frequência, como tabs, dropdowns, modais.
<template>
<!-- v-if: element removed from DOM when false -->
<div v-if="isLoggedIn">Welcome back</div>
<!-- v-show: element stays, display toggles -->
<div v-show="isLoggedIn">Welcome back</div>
</template>
<!-- v-show compiles to: -->
<!-- <div style="display: none;">Welcome back</div> when false -->
<!-- v-if does not render the element at all when false -->Cadeia v-if com v-else
v-else-if e v-else devem seguir imediatamente um elemento v-if (ou outro v-else-if) — nenhum outro elemento pode estar entre eles. A cadeia avalia de cima para baixo e para na primeira condição truthy. O v-else final captura cada um dos casos restantes. Este padrão é ótimo para UI baseada em status (carregando, erro, vazio, sucesso).
<template>
<div v-if="status === 'loading'">Loading...</div>
<div v-else-if="status === 'error'">Error occurred</div>
<div v-else-if="status === 'empty'">No items</div>
<div v-else>
<ul>
<li v-for="item in items" :key="item.id">{{ item.name }}</li>
</ul>
</div>
</template>Wrapper <template> para v-if
<template> é um wrapper lógico que não renderiza no DOM — perfeito para agrupar múltiplos elementos sob um v-if ou v-for sem adicionar HTML extra. Isso mantém sua marcação semântica (sem divs perdidos). Para v-for no template, você ainda precisa de :key no próprio elemento template.
<template>
<!-- group elements under one condition, no wrapper div -->
<template v-if="showProfile">
<h2>{{ user.name }}</h2>
<p>{{ user.bio }}</p>
<button @click="edit">Edit</button>
</template>
<!-- combine v-if with v-for on template -->
<template v-for="item in items" :key="item.id">
<dt>{{ item.term }}</dt>
<dd>{{ item.def }}</dd>
</template>
</template>Prioridade v-if vs v-for
Nunca use v-if e v-for no mesmo elemento. No Vue 3, v-if tem prioridade maior, então roda antes de v-for — a variável do loop ainda não está disponível, causando erros. Em vez disso, filtre o array com uma propriedade computada (preferido) ou .filter() inline. Use um <template v-for> envolvente com um v-if interno, se necessário.
<template>
<!-- AVOID: v-if and v-for on same element -->
<!-- In Vue 3, v-if has higher priority than v-for -->
<!-- so 'item' is not defined when v-if evaluates -->
<li v-for="item in items" v-if="item.active" :key="item.id">
{{ item.name }}
</li>
<!-- GOOD: filter first, then iterate -->
<li
v-for="item in items.filter(i => i.active)"
:key="item.id"
>
{{ item.name }}
</li>
<!-- BEST: use computed for the filtered list -->
</template>Transition com v-if
Envolva um elemento v-if (ou v-show) em <Transition> para animar entrada/saída. O Vue adiciona classes nos momentos certos: v-enter-from, v-enter-active, v-enter-to (e v-leave-*). Defina transições CSS nessas classes. name='fade' troca o prefixo 'v-' por 'fade-'. Transition suporta só um elemento filho — use TransitionGroup para listas.
<template>
<Transition name="fade">
<p v-if="show">Hello</p>
</Transition>
</template>
<style>
.fade-enter-active, .fade-leave-active {
transition: opacity 0.3s;
}
.fade-enter-from, .fade-leave-to {
opacity: 0;
}
</style>Renderização de Listas
v-for com Arrays
v-for itera arrays, expondo cada item e (opcionalmente) o índice. SEMPRE vincule :key a um valor único estável como item.id — isso permite que o Vue case nós antigos e novos durante reordenações, preservando o estado dos componentes e o DOM com eficiência. Usar o índice como key quebra quando itens são inseridos/removidos/reordenados, causando bugs sutis.
<script setup>
import { ref } from 'vue'
const items = ref([
{ id: 1, name: 'Apple' },
{ id: 2, name: 'Banana' },
{ id: 3, name: 'Cherry' }
])
</script>
<template>
<!-- always provide :key with stable unique id -->
<li v-for="item in items" :key="item.id">
{{ item.name }}
</li>
<!-- with index (avoid as :key) -->
<li v-for="(item, index) in items" :key="item.id">
{{ index + 1 }}. {{ item.name }}
</li>
</template>v-for com Objetos e Intervalo
v-for sobre um objeto itera valores por padrão; o segundo argumento é a chave, o terceiro o índice. A ordem de iteração do objeto segue Object.keys() (ordem de inserção para chaves de string). v-for com um número n itera de 1 a n (inclusivo, não de 0 a n-1). Para listas filtradas ou ordenadas, prefira uma propriedade computada à lógica inline, por legibilidade e cache.
<template>
<!-- iterate object: (value, key, index) -->
<div v-for="(value, key, index) in user" :key="key">
{{ index }}. {{ key }}: {{ value }}
</div>
<!-- iterate a number range (1 to n inclusive) -->
<span v-for="n in 10" :key="n">{{ n }} </span>
<!-- 1 2 3 4 5 6 7 8 9 10 -->
<!-- use v-for of computed for derived lists -->
<li v-for="todo in doneTodos" :key="todo.id">
{{ todo.text }}
</li>
</template>Detecção de Mudanças em Listas
Vue 3 usa reatividade baseada em Proxy, então mutar arrays com push, pop, splice, sort, reverse dispara atualizações — sem ressalvas especiais (diferente do Vue 2). Substituir o array inteiro (items.value = novoArray) também funciona, porque o setter do value do ref aciona a reatividade. Filter/map produzem novos arrays — atribua-os de volta para atualizar.
<script setup>
import { ref } from 'vue'
const items = ref([1, 2, 3])
// MUTATION methods (Vue 3 detects these via Proxy)
items.value.push(4) // add
items.value.pop() // remove last
items.value.splice(1, 1) // remove at index
items.value.sort() // sort
// REPLACEMENT (always reactive)
items.value = items.value.filter(n => n > 1)
items.value = [...items.value, 5]
</script>TransitionGroup para Listas
TransitionGroup anima listas v-for: entrada, saída E movimento (quando itens mudam de posição). Diferente de Transition, renderiza um elemento real (definido via tag). Cada filho PRECISA de um :key único. A classe .list-move anima itens deslizando às novas posições quando a lista se reordena — um efeito polido que CSS puro não alcança. leave-active precisa de position: absolute para movimentos suaves.
<template>
<TransitionGroup name="list" tag="ul">
<li v-for="item in items" :key="item.id">
{{ item.text }}
</li>
</TransitionGroup>
</template>
<style>
.list-enter-active, .list-leave-active {
transition: all 0.5s ease;
}
.list-enter-from, .list-leave-to {
opacity: 0;
transform: translateX(30px);
}
/* animate items moving to new positions */
.list-move {
transition: transform 0.5s ease;
}
</style>Desempenho: v-memo
v-memo é uma dica de otimização. O Vue pula re-renderizar o elemento, a menos que um dos valores do array de dependências mude. Para listas grandes em que a maioria dos itens não muda a cada atualização, isso pode reduzir dramaticamente as re-renderizações. Use só quando mediu um problema de desempenho — otimização prematura adiciona complexidade e risco de UI velha.
<template>
<!-- skip re-render of this item unless 'id' or 'selected' changes -->
<div
v-for="item in hugeList"
:key="item.id"
v-memo="[item.id, item.id === selectedId]"
>
{{ item.name }} — {{ item.id === selectedId ? '★' : '' }}
</div>
</template>Tratamento de Eventos
Handlers Inline
@click (abreviação de v-on:click) vincula um handler de clique. Instruções inline (count++) funcionam para casos simples. Um handler inline (greet) recebe automaticamente o evento nativo como primeiro argumento. Para passar argumentos personalizados E o evento, chame a função explicitamente com $event: greet('oi', $event).
<script setup>
import { ref } from 'vue'
const count = ref(0)
const name = ref('Vue')
function greet(event) {
alert('Hello ' + name.value)
// event is the native DOM event
console.log(event.target.tagName)
}
</script>
<template>
<!-- inline statement -->
<button @click="count++">Add</button>
<!-- method reference (auto-receives event) -->
<button @click="greet">Greet</button>
<!-- call with custom args (use $event for native event) -->
<button @click="greet($event)">Greet</button>
</template>Modificadores de Evento
Modificadores de evento se encadeiam depois do nome do evento com um ponto. .prevent e .stop são os mais comuns (envio de formulário, borbulhamento de evento). .self garante que o handler dispare só quando o próprio elemento (não um filho) for clicado. .passive diz ao navegador que o handler não chamará preventDefault, habilitando rolagem mais suave — importante para handlers de toque/rolagem.
<template>
<!-- .prevent: call preventDefault() -->
<form @submit.prevent="onSubmit">...</form>
<!-- .stop: call stopPropagation() -->
<div @click="outer">
<button @click.stop="inner">Won't bubble</button>
</div>
<!-- .self: only trigger if event.target === current element -->
<div @click.self="onSelf">Only direct clicks</div>
<!-- .once: handler removed after first invocation -->
<button @click.once="init">Init once</button>
<!-- .capture: use capture phase instead of bubble -->
<div @click.capture="onCapture">...</div>
<!-- .passive: improve scroll perf (no preventDefault) -->
<div @scroll.passive="onScroll">...</div>
</template>Modificadores de Tecla e Sistema
Modificadores de tecla filtram eventos de teclado pelo nome da tecla (.enter, .esc, .delete, .space, .tab, .up, .down, .left, .right). Modificadores de sistema (.ctrl, .alt, .shift, .meta) exigem que aquela tecla esteja pressionada. .exact garante que NENHUM outro modificador de sistema esteja pressionado — @click.ctrl.exact dispara só em Ctrl+Clique, não Ctrl+Shift+Clique. Use kebab-case para teclas que o Vue não tem apelido (page-down).
<template>
<!-- key modifiers: only fire on specific keys -->
<input @keyup.enter="submit" />
<input @keyup.esc="cancel" />
<input @keyup.delete="remove" />
<!-- system modifiers: ctrl, alt, shift, meta -->
<button @click.ctrl="openInNewTab">Ctrl+Click</button>
<input @keyup.alt.enter="altEnter" />
<!-- .exact: no other modifiers can be pressed -->
<button @click.ctrl.exact="onCtrlOnly">Ctrl only</button>
<!-- any key code via kebab-case (deprecated but works) -->
<input @keyup.page-down="onPageDown" />
</template>Eventos Personalizados com emit
Componentes filhos emitem eventos para se comunicar para cima. defineEmits declara os nomes dos eventos (usados para validação e dicas de IDE). O pai escuta com @nome-evento. Payloads são passados como argumentos adicionais ao emit e recebidos pelo handler do pai. Por convenção, use nomes de eventos kebab-case nos templates (meu-evento), camelCase no defineEmits (meuEvento) — o Vue converte automaticamente.
<!-- ChildButton.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])
function onClick() {
// emit with payload
emit('increment', 1)
}
</script>
<template>
<button @click="onClick">+1</button>
</template>
<!-- Parent.vue -->
<template>
<ChildButton @increment="onIncrement" @delete="remove" />
</template>
<script setup>
function onIncrement(amount) {
console.log('incremented by', amount)
}
</script>v-model em Componentes
defineModel() é a macro moderna (Vue 3.4+) para binding bidirecional em componentes — retorna um ref que sincroniza automaticamente com o v-model do pai. Para múltiplos bindings, use modelos nomeados: v-model:campo. Por baixo, isso emite 'update:modelValue' (ou 'update:campo') e o pai sincroniza o ref vinculado. Código antigo usa defineProps + defineEmits manualmente.
<!-- CustomInput.vue -->
<script setup>
const model = defineModel()
</script>
<template>
<input :value="model" @input="model = $event.target.value" />
</template>
<!-- Parent.vue -->
<template>
<CustomInput v-model="text" />
</template>
<!-- multiple v-models (Vue 3.4+) -->
<template>
<UserForm v-model:name="name" v-model:email="email" />
</template>Bindings de Formulário
Text e Textarea
v-model em inputs de texto sincroniza a cada evento input. Para textarea, ponha v-model direto no elemento (não como :value — conteúdo multilinha em atributo não funciona). Modificadores: .lazy sincroniza no blur/change (menos atualizações), .trim remove espaços, .number converte o valor para Number. Encadeie modificadores: v-model.lazy.trim.
<script setup>
import { ref } from 'vue'
const text = ref('')
const message = ref('')
</script>
<template>
<!-- text input: binds on every keystroke -->
<input v-model="text" placeholder="Type here" />
<p>You typed: {{ text }}</p>
<!-- textarea: insert tags inside, not :value -->
<textarea v-model="message" rows="4"></textarea>
<p>Preview: {{ message }}</p>
<!-- .lazy: sync on 'change' (blur) instead of 'input' -->
<input v-model.lazy="text" />
<!-- .trim: strip leading/trailing whitespace -->
<input v-model.trim="text" />
<!-- .number: cast to Number (NaN if invalid) -->
<input v-model.number="age" type="number" />
</template>Checkbox e Radio
Um checkbox único vincula a um booleano (marcado = true). Múltiplos checkboxes compartilhando o mesmo v-model vinculam a um array dos seus atributos value — marcar adiciona o valor, desmarcar remove. Radio buttons compartilhando um v-model vinculam o valor da opção escolhida ao ref. Use atributos true-value / false-value para personalizar o mapeamento booleano.
<script setup>
import { ref } from 'vue'
const agreed = ref(false)
const fruits = ref([]) // array for multi-checkbox
const picked = ref('') // string for radio
</script>
<template>
<!-- single checkbox -> boolean -->
<input type="checkbox" v-model="agreed" /> I agree
<!-- multiple checkboxes with same v-model -> array -->
<input type="checkbox" value="apple" v-model="fruits" /> Apple
<input type="checkbox" value="banana" v-model="fruits" /> Banana
<input type="checkbox" value="cherry" v-model="fruits" /> Cherry
<p>Selected: {{ fruits }}</p>
<!-- radio: value binds to the chosen option -->
<input type="radio" value="A" v-model="picked" /> A
<input type="radio" value="B" v-model="picked" /> B
</template>Select
Em <select>, v-model vai no elemento select (não nas options) e sincroniza com o valor da opção escolhida. Use uma opção de placeholder desabilitada com valor vazio para a UX 'por favor selecione'. Para opções dinâmicas, renderize-as com v-for e vincule :value. Adicione o atributo multiple para permitir multi-seleção — v-model então vincula a um array de valores selecionados.
<script setup>
import { ref } from 'vue'
const selected = ref('')
const multi = ref([])
const options = [
{ value: 'a', label: 'Option A' },
{ value: 'b', label: 'Option B' }
]
</script>
<template>
<!-- single select -->
<select v-model="selected">
<option disabled value="">Please select</option>
<option value="a">A</option>
<option value="b">B</option>
</select>
<!-- dynamic options -->
<select v-model="selected">
<option v-for="opt in options" :key="opt.value" :value="opt.value">
{{ opt.label }}
</option>
</select>
<!-- multi-select (hold Ctrl/Cmd) -> array -->
<select v-model="multi" multiple>
<option value="x">X</option>
<option value="y">Y</option>
</select>
</template>Envio e Validação de Formulário
Use @submit.prevent para tratar o envio do formulário, prevenindo o recarregamento padrão da página. Objetos de formulário reativos agrupam campos relacionados. Para validação, bibliotecas como VeeValidate ou Zod + um composable são populares para formulários complexos, mas uma função validate() simples retornando um objeto de erros funciona bem para formulários pequenos. Sempre previna o padrão para habilitar envios estilo SPA.
<script setup>
import { reactive, ref } from 'vue'
const form = reactive({
email: '',
password: ''
})
const errors = ref({})
function validate() {
errors.value = {}
if (!form.email.includes('@')) errors.value.email = 'Invalid email'
if (form.password.length < 6) errors.value.password = 'Too short'
return Object.keys(errors.value).length === 0
}
function onSubmit() {
if (!validate()) return
// submit form...
}
</script>
<template>
<form @submit.prevent="onSubmit">
<input v-model.trim="form.email" />
<span v-if="errors.email">{{ errors.email }}</span>
<input type="password" v-model="form.password" />
<span v-if="errors.password">{{ errors.password }}</span>
<button type="submit">Submit</button>
</form>
</template>v-model com Componentes Personalizados
Envolva campos de formulário em componentes personalizados para reuso. defineModel() retorna um ref que lê o valor do pai e escreve de volta via o emit 'update:modelValue'. O componente vincula :value ao modelo e @input o atualiza. Esse padrão permite construir um design-system consistente de inputs de formulário (BaseInput, BaseSelect, BaseCheckbox) utilizáveis com v-model como elementos nativos.
<!-- BaseInput.vue -->
<script setup>
const model = defineModel()
defineProps({
label: String,
type: { type: String, default: 'text' }
})
</script>
<template>
<label>
{{ label }}
<input
:type="type"
:value="model"
@input="model = $event.target.value"
/>
</label>
</template>
<!-- Usage -->
<template>
<BaseInput v-model="email" label="Email" type="email" />
</template>Componentes
Definindo e Usando Componentes
Um componente é um arquivo .vue com template, script e style opcional. Importe-o (registrado automaticamente localmente em <script setup>) e use-o como uma tag HTML personalizada. Nomes de componentes são PascalCase no script e podem ser kebab-case (meu-botao) nos templates — o Vue normaliza. Componentes registrados globalmente (app.component) estão disponíveis em qualquer lugar sem import.
<!-- MyButton.vue -->
<template>
<button class="btn"><slot /></button>
</template>
<!-- App.vue -->
<script setup>
import MyButton from './MyButton.vue'
</script>
<template>
<MyButton>Click me</MyButton>
</template>Componentes Dinâmicos
<component :is='...'> renderiza um componente dinamicamente — o valor pode ser uma string de nome registrado, um objeto de componente importado ou um defineAsyncComponent. Envolva em <keep-alive> para preservar o estado do componente (input de formulário, posição de rolagem) ao alternar entre abas. Use shallowRef (não ref) para objetos de componente, evitando o custo de reatividade profunda.
<script setup>
import { ref, shallowRef } from 'vue'
import HomeTab from './HomeTab.vue'
import PostsTab from './PostsTab.vue'
import ArchiveTab from './ArchiveTab.vue'
const tabs = { HomeTab, PostsTab, ArchiveTab }
const current = shallowRef('HomeTab')
// keep component state when switching (e.g. form input)
import { keep-alive } from 'vue' // not real — use the tag
</script>
<template>
<button v-for="(comp, name) in tabs" :key="name" @click="current = name">
{{ name }}
</button>
<keep-alive>
<component :is="tabs[current]" />
</keep-alive>
</template>Componentes Assíncronos
defineAsyncComponent carrega um componente preguiçosamente no primeiro render — o chunk é buscado sob demanda, reduzindo o tamanho inicial do bundle. Configure estados de carregamento/erro para uma UX suave. Combine com Suspense para coordenar múltiplos componentes assíncronos. O loader retorna uma Promise do módulo do componente (Vite/Webpack dividem automaticamente com base no import() dinâmico).
<script setup>
import { defineAsyncComponent } from 'vue'
// lazy-load on first use (code-split)
const HeavyChart = defineAsyncComponent(() =>
import('./HeavyChart.vue')
)
// with loading, error, delay, timeout states
const AdminPanel = defineAsyncComponent({
loader: () => import('./AdminPanel.vue'),
loadingComponent: LoadingSpinner,
errorComponent: ErrorMsg,
delay: 200, // show loading after 200ms
timeout: 5000 // error if not loaded in 5s
})
</script>
<template>
<HeavyChart />
<AdminPanel />
</template>v-model de Componente (Múltiplo)
Modelos nomeados permitem que um único componente exponha múltiplos bindings bidirecionais. defineModel('nome') declara cada um. O pai usa v-model:nome='...'. Ótimo para componentes de formulário que reúnem vários campos (ex.: um componente de endereço com rua, cidade, CEP). O v-model padrão (sem nome) mapeia para 'modelValue'.
<!-- UserForm.vue -->
<script setup>
const firstName = defineModel('firstName')
const lastName = defineModel('lastName')
</script>
<template>
<input v-model="firstName" />
<input v-model="lastName" />
</template>
<!-- Parent.vue -->
<template>
<UserForm
v-model:firstName="form.first"
v-model:lastName="form.last"
/>
</template>Componentes Recursivos e Circulares
Um componente pode se referenciar pelo próprio nome de arquivo (autorreferência automática). Perfeito para estruturas de árvore (árvores de arquivos, threads de comentários, menus). Para referências circulares entre dois componentes (A importa B, B importa A), use defineAsyncComponent para um deles, ou importe no beforeCreate. O Vue trata componentes recursivos, mas cuidado com loops infinitos — sempre tenha um caso base (sem filhos).
<!-- TreeNode.vue -->
<script setup>
defineProps({
node: Object
})
// a component can reference itself by its filename
// TreeNode.vue can use <TreeNode /> recursively
</script>
<template>
<div>
{{ node.label }}
<ul v-if="node.children?.length">
<li v-for="child in node.children" :key="child.id">
<TreeNode :node="child" />
</li>
</ul>
</div>
</template>Props
Declarando Props
defineProps declara o contrato de entrada de um componente. A declaração em runtime suporta type, default, required e validator. A declaração baseada em tipos do Vue 3 (só TS) dá segurança de tipos, mas perde a validação em runtime (use com volar + uma biblioteca de validadores). Padrões para objetos/arrays precisam de função factory: default: () => [].
<script setup>
// runtime declaration (validates types)
const props = defineProps({
title: String,
count: { type: Number, default: 0 },
items: { type: Array, required: true },
callback: { type: Function, default: () => {} },
status: {
type: String,
validator: (v) => ['active', 'idle'].includes(v)
}
})
// type-based declaration (TS only, no runtime validation)
const props2 = defineProps<{
title: string
count?: number
}>()
</script>Nomeação e Passagem de Props
Props devem ser camelCase no JS (mensagemSaudacao) e kebab-case nos templates (mensagem-saudacao) — HTML é insensível a caixa, então kebab-case é mais seguro. O Vue converte automaticamente entre os dois. Props de string estáticas usam sintaxe de atributo simples; valores dinâmicos usam :prop. Passe números/booleanos/objetos sempre com :, para não serem tratados como strings.
<!-- Child.vue -->
<script setup>
defineProps({
greetingMessage: String,
userId: Number
})
</script>
<!-- Parent.vue -->
<template>
<!-- kebab-case in templates (HTML-friendly) -->
<Child greeting-message="Hello" :user-id="42" />
<!-- camelCase also works in SFC templates -->
<Child greetingMessage="Hello" :userId="42" />
</template>Fluxo de Dados Unidirecional
Props são somente leitura — nunca as mute diretamente. O Vue avisa no modo dev. Para mudar o valor de uma prop, emita um evento e deixe o pai atualizá-lo (fluxo de dados unidirecional). Para uma cópia de trabalho local, inicialize um ref a partir da prop e sincronize via watch. O padrão bidirecional mais limpo é v-model com defineModel, que abstrai a dança do emit-e-atualiza.
<!-- BAD: mutating a prop -->
<script setup>
const props = defineProps(['count'])
function inc() {
props.count++ // WARNING: don't mutate props!
}
</script>
<!-- GOOD: emit to parent, or use local copy -->
<script setup>
import { ref, watch } from 'vue'
const props = defineProps(['count'])
const emit = defineEmits(['update:count'])
// local copy that syncs with prop
const local = ref(props.count)
watch(() => props.count, v => local.value = v)
function inc() {
local.value++
emit('update:count', local.value)
}
</script>Validação e Padrões de Props
O Vue valida props no modo dev e avisa em falha (não em produção). type aceita um construtor (String, Number, Boolean, Array, Object, Function, Symbol) ou um array deles. Padrões de Object e Array PRECISAM ser funções retornando uma nova instância — senão cada um dos componentes compartilhariam a mesma referência padrão (bugs de mutação). Validadores rodam após as checagens de tipo.
<script setup>
const props = defineProps({
// type can be an array of allowed types
value: { type: [String, Number], required: true },
// object/array default MUST be a factory function
list: {
type: Array,
default: () => []
},
// custom validator
age: {
type: Number,
validator: (v) => v >= 0 && v <= 150
},
// multiple checks combined
email: {
type: String,
required: true,
validator: (v) => v.includes('@')
}
})
</script>Cast Booleano e Fallthrough de Atributos
Props booleanas têm cast especial: presença sem valor significa true. O fallthrough de atributos passa atributos não-prop (class, style, id, data-*) ao elemento raiz automaticamente. Múltiplas raízes exigem v-bind='$attrs' explícito no elemento desejado. Desative o fallthrough com defineOptions({ inheritAttrs: false }) para controle total.
<!-- prop declared as Boolean -->
<script setup>
defineProps({
disabled: Boolean,
active: Boolean
})
</script>
<!-- Parent -->
<template>
<MyButton disabled /> <!-- disabled = true -->
<MyButton :disabled="false" /> <!-- disabled = false -->
<MyButton /> <!-- disabled = undefined -->
</template>
<!-- Attribute fallthrough: non-prop attributes
land on the root element automatically -->
<template>
<!-- <MyButton data-id="5" class="large" /> -->
<!-- the data-id and class merge onto the <button> root -->
<button>...</button>
</template>Emits
Declarando e Emitindo
defineEmits declara os eventos que um componente pode emitir. A forma de objeto permite validadores que recebem o payload e retornam false para avisar (modo dev). Emits sobem na árvore — pais escutam com @nome-evento. Sempre declare emits explicitamente: documenta a API, habilita exclusão do fallthrough de attrs e suporta validação. emit() recebe o nome do evento mais argumentos de payload opcionais.
<script setup>
// declare emits (with optional validation)
const emit = defineEmits({
// null-ish = no validation
click: null,
// function = validate payload
submit: (payload) => {
if (!payload.email) {
console.warn('submit needs email')
return false
}
return true
}
})
function handleSubmit() {
emit('submit', { email: '[email protected]', name: 'Alice' })
}
</script>Escutando Emits
Pais escutam com @nome-evento (ou v-on:nome-evento). O handler recebe qualquer payload emitido. Arrow functions inline são práticas para transformações simples (@incrementar='n => contador += n'). Handlers nomeados recebem automaticamente o payload como primeiro argumento. Eventos DOM nativos no elemento raiz de um componente passam adiante, a menos que declarados em emits — declarar 'click' o torna um evento personalizado.
<!-- Child.vue -->
<script setup>
const emit = defineEmits(['increment', 'delete'])
function click() {
emit('increment', 5)
}
</script>
<template>
<button @click="click">+5</button>
</template>
<!-- Parent.vue -->
<template>
<!-- inline handler -->
<Child @increment="n => count += n" />
<!-- method handler -->
<Child @increment="onIncrement" @delete="onDelete" />
</template>
<script setup>
function onIncrement(amount) {
console.log('incremented by', amount)
}
</script>Implementação de v-model
v-model num componente é açúcar para :modelValue + @update:modelValue. O filho recebe o valor via a prop modelValue e emite update:modelValue para sincronizar. Este é o padrão manual; defineModel() (Vue 3.4+) o embrulha. Para v-model nomeado (v-model:foo), use a prop foo e o evento update:foo. Isso permite construir componentes de formulário que funcionam como inputs nativos.
<!-- CustomInput.vue (manual implementation) -->
<script setup>
const props = defineProps(['modelValue'])
const emit = defineEmits(['update:modelValue'])
function onInput(e) {
emit('update:modelValue', e.target.value)
}
</script>
<template>
<input
:value="modelValue"
@input="onInput"
/>
</template>
<!-- Parent -->
<template>
<CustomInput v-model="text" />
</template>Validação de Emit
Validadores de emit recebem os argumentos do payload e retornam false para acionar um aviso em modo dev. Eles não impedem o emit — apenas avisam. Isso captura violações de contrato cedo no desenvolvimento. Use-os para documentar as formas esperadas de payload. Em produção, validadores são removidos, então não conte com eles para segurança ou fluxo de controle.
<script setup>
const emit = defineEmits({
// no validation
click: null,
// validate payload; return false to warn
change: (value) => {
if (typeof value !== 'string') {
console.warn('change payload must be string')
return false
}
return true
},
// validate multiple args
update: (id, value) => {
if (!id || value === undefined) return false
return true
}
})
// validation runs on emit
emit('change', 123) // warns: must be string
</script>Eventos vs Props: Quando Usar
Siga o fluxo de dados unidirecional: props para baixo, eventos para cima. Para binding bidirecional, use v-model (açúcar de props + emit). Para comunicação profundamente aninhada, perfuração de props fica dolorosa — use provide/inject para injeção de dependência ou uma store (Pinia) para estado compartilhado. Eventos são para notificações de 'algo aconteceu'; props são para 'aqui está seu dado'.
<!-- Parent-to-child: props (down) -->
<template>
<Child :data="parentData" :config="config" />
</template>
<!-- Child-to-parent: emits (up) -->
<template>
<Child @change="onChange" @submit="onSubmit" />
</template>
<!-- Two-way: v-model (combines both) -->
<template>
<Child v-model="value" />
</template>
<!-- For complex state, prefer provide/inject or a store -->Slots
Slot Padrão
Slots permitem que um pai injete conteúdo no template de um componente filho. O elemento <slot> é o espaço reservado. O conteúdo filho do pai preenche o slot padrão. Slots habilitam composição: Card cuida do estilo do wrapper, o pai controla o conteúdo interno. Sem slots, você precisaria de uma prop para cada elemento interno possível — slots são muito mais flexíveis.
<!-- Card.vue -->
<template>
<div class="card">
<slot />
</div>
</template>
<!-- Usage -->
<template>
<Card>
<p>This goes into the default slot</p>
<button>Action</button>
</Card>
</template>Slots Nomeados
Slots nomeados permitem que um componente tenha múltiplos espaços reservados de conteúdo. Declare com <slot name='foo' />, preencha com <template #foo>. O # é abreviação de v-slot:. O slot sem nome é o slot 'default' — conteúdo sem wrapper de template vai para lá. Slots nomeados são perfeitos para layouts (header, sidebar, main, footer) em que o pai preenche cada região.
<!-- Layout.vue -->
<template>
<header><slot name="header" /></header>
<main><slot /></main>
<footer><slot name="footer" /></footer>
</template>
<!-- Usage with # shorthand -->
<template>
<Layout>
<template #header>
<h1>My Page Title</h1>
</template>
<!-- default slot (no #name) -->
<p>Main content here</p>
<template #footer>
<p>© 2025</p>
</template>
</Layout>
</template>Slot Props (Slots com Escopo)
Slots com escopo permitem que um filho passe dados de volta ao conteúdo do slot do pai. O filho vincula dados em <slot :item='item'>; o pai os recebe via v-slot='{ item }' (ou #default='{ item }'). Esta é a fundação de componentes de lista reutilizáveis (tabela de dados, lista virtual): o filho cuida da iteração, o pai controla a renderização de cada item.
<!-- List.vue -->
<template>
<ul>
<li v-for="item in items" :key="item.id">
<slot :item="item" :index="index" />
</li>
</ul>
</template>
<script setup>
defineProps(['items'])
</script>
<!-- Usage: receive slot props via v-slot -->
<template>
<List :items="todos">
<template #default="{ item, index }">
<input type="checkbox" v-model="item.done" />
<span :class="{ done: item.done }">{{ index }}: {{ item.text }}</span>
</template>
</List>
</template>Conteúdo Padrão de Slot
O conteúdo de fallback do slot vai entre <slot> e </slot>. Renderiza só quando o pai não fornece conteúdo de slot. Ótimo para padrões sensatos — um rótulo de botão, uma mensagem de estado vazio, um placeholder. Se o pai passa até uma string vazia, o fallback é sobrescrito.
<!-- Button.vue -->
<template>
<button>
<slot>Click here</slot> <!-- fallback content -->
</button>
</template>
<!-- Usage -->
<template>
<Button /> <!-- renders "Click here" -->
<Button>Save</Button> <!-- renders "Save" -->
</template>Escopo de Render e Use Slots
O conteúdo do slot é renderizado no escopo do PAI — pode acessar o estado do pai, mas não o do filho diretamente (a menos que via slot props). Essa separação deixa o filho cuidar da mecânica (paginação, virtualização, busca) enquanto o pai controla a apresentação. O padrão de slot com escopo (FancyList + UserCard) é uma técnica de composição poderosa — o filho é dono do fluxo de dados, o pai da renderização.
<!-- FancyList.vue (scoped slot pattern) -->
<script setup>
const props = defineProps(['items', 'pageSize'])
import { ref, computed } from 'vue'
const page = ref(1)
const paged = computed(() =>
props.items.slice((page.value - 1) * props.pageSize, page.value * props.pageSize)
)
</script>
<template>
<div v-for="item in paged" :key="item.id">
<slot :item="item" :page="page" />
</div>
</template>
<!-- Usage: parent fully controls rendering -->
<FancyList :items="users" :pageSize="10">
<template #default="{ item, page }">
<UserCard :user="item" />
<small>Page {{ page }}</small>
</template>
</FancyList>Hooks de Ciclo de Vida
Hooks da Composition API
Hooks de ciclo de vida rodam em estágios específicos. onMounted dispara após o DOM ser renderizado (seguro para acessar elementos, rodar bibliotecas de canvas, buscar dados). onUpdated dispara após cada atualização reativa — evite mutar estado aqui (loop infinito). onUnmounted serve para limpeza (timers, listeners, assinaturas). Hooks precisam ser chamados sincronamente no setup, mas podem ser chamados várias vezes.
<script setup>
import {
onBeforeMount, onMounted,
onBeforeUpdate, onUpdated,
onBeforeUnmount, onUnmounted,
onActivated, onDeactivated,
onErrorCaptured
} from 'vue'
onBeforeMount(() => console.log('before mount'))
onMounted(() => console.log('mounted — DOM ready'))
onBeforeUpdate(() => console.log('before re-render'))
onUpdated(() => console.log('after re-render'))
onBeforeUnmount(() => console.log('before unmount'))
onUnmounted(() => console.log('unmounted — cleanup'))
</script>Setup vs Created
Em <script setup>, o corpo inteiro do script roda durante a inicialização do componente — equivalente a beforeCreate + created na Options API. Não há hook created() separado. Código de nível superior (declarações, chamadas de função, até trabalho assíncrono) roda uma vez por instância. Para busca de dados, este é um lugar comum para começar (embora onMounted também seja bom — o fetch começa igual).
<script setup>
// <script setup> runs BEFORE the component is mounted
// (equivalent to beforeCreate + created in Options API)
import { ref } from 'vue'
// this code runs once per component instance,
// before reactive state is exposed to the template
const count = ref(0)
console.log('component created, count =', count.value)
// no need for created() hook — just run code here
fetch('/api/data')
.then(r => r.json())
.then(data => { /* ... */ })
</script>Mounted e Limpeza
Pares de setup/limpeza são essenciais: cada listener, timer, assinatura ou observador adicionado em onMounted PRECISA ser removido em onUnmounted. Não limpar causa vazamentos de memória e handlers zumbis disparando em componentes destruídos. O padrão: addEventListener em onMounted, removeEventListener em onUnmounted. Para watchers, use a função stop retornada ou eles se limpam sozinhos ao desmontar.
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
const windowWidth = ref(window.innerWidth)
function onResize() {
windowWidth.value = window.innerWidth
}
onMounted(() => {
// setup side effects after DOM is ready
window.addEventListener('resize', onResize)
console.log('mounted')
})
onUnmounted(() => {
// ALWAYS clean up to avoid memory leaks
window.removeEventListener('resize', onResize)
})
</script>Hooks de KeepAlive
Quando um componente é envolvido em <KeepAlive>, trocar para fora não o desmonta — ele é desativado (cacheado). onActivated e onDeactivated disparam ao mostrar/esconder. Use-os para pausar/retomar trabalho (polling, reprodução de vídeo) sem setup/teardown completo. onMounted ainda dispara uma vez (primeira ativação); onUnmounted nunca dispara enquanto cacheado. Esses hooks permitem otimizar o uso de recursos para abas cacheadas.
<script setup>
import { onActivated, onDeactivated } from 'vue'
// these fire when the component is wrapped in <KeepAlive>
// and is being shown (activated) or hidden (deactivated)
onActivated(() => {
console.log('component shown again — resume polling')
startPolling()
})
onDeactivated(() => {
console.log('component hidden but not unmounted — pause')
stopPolling()
})
// onMounted fires only once (first show)
// onActivated fires every time it's re-shown
</script>Error Captured
onErrorCaptured captura erros de componentes descendentes (em templates, render, ciclo de vida, watchers). Recebe (erro, instancia, info). Retorne false para impedir que o erro se propague aos handlers errorCaptured dos pais e ao errorHandler global. Use em componentes de fronteira que tratam graciosamente erros de filhos (como React Error Boundaries). Combine com Suspense para estados de erro assíncronos.
<script setup>
import { onErrorCaptured, ref } from 'vue'
const error = ref(null)
onErrorCaptured((err, instance, info) => {
// err: the error thrown
// instance: component that threw
// info: lifecycle hook or event name where it occurred
error.value = err.message
console.error('Captured:', err, info)
// return false to stop propagation to parent
return false
})
</script>
<template>
<div v-if="error" class="error">{{ error }}</div>
<slot v-else />
</template>Composition API
ref vs reactive
ref() funciona com qualquer valor (primitivos, objetos). O acesso reativo exige .value no JS, mas desembrulha automaticamente nos templates. reactive() só funciona em objetos/arrays — sem .value. Use ref para primitivos e valores substituíveis; use reactive para estado agrupado. Regra prática: prefira ref() para valores individuais, reactive() para objetos de estado. Misturar é ok — refs se desembrulham automaticamente dentro de objetos reativos.
<script setup>
import { ref, reactive } from 'vue'
// ref: works with any value, access via .value
const count = ref(0)
count.value++
console.log(count.value) // 1
// reactive: only for objects/arrays, no .value needed
const state = reactive({ count: 0, user: { name: 'A' } })
state.count++
console.log(state.count) // 1
// refs auto-unwrap in templates and reactive objects
const wrapper = reactive({ count }) // wrapper.count === count.value
</script>Armadilhas do reactive
Objetos reativos têm duas armadilhas: você não pode reatribuir a variável (state = novoObj) — mute propriedades (state.list = []). A desestruturação perde reatividade, porque a variável desestruturada é um snapshot. Use toRefs() para converter propriedades reativas em refs que permanecem ligadas. Essas armadilhas são a razão de muitos devs preferirem ref() — é substituível (basta definir .value) e amigável à desestruturação.
<script setup>
import { reactive, ref } from 'vue'
const state = reactive({ list: [1, 2, 3] })
// PITFALL 1: replacing the whole object loses reactivity
// state = reactive({ list: [4, 5] }) // ERROR: reassign
// GOOD: mutate properties
state.list = [4, 5]
// PITFALL 2: destructuring loses reactivity
let { list } = state // 'list' is now plain
// list.push(4) won't trigger updates
// FIX: use toRefs to keep reactivity
import { toRefs } from 'vue'
const { list } = toRefs(state) // now list is a ref
</script>toRef e toRefs
toRef() converte uma única propriedade reativa num ref que permanece ligado (mutar um afeta o outro). toRefs() converte TODAS as propriedades — útil para retornar estado reativo de composables preservando a desestruturação. Sem toRefs, valores desestruturados perdem reatividade. Padrão: o composable retorna toRefs(state) para que consumidores possam desestruturar sem quebrar a reatividade.
<script setup>
import { reactive, toRef, toRefs } from 'vue'
const state = reactive({
count: 0,
name: 'Alice'
})
// toRef: single property -> ref (stays linked to state)
const countRef = toRef(state, 'count')
// toRefs: all properties -> object of refs
const { count, name } = toRefs(state)
countRef.value++ // updates state.count
count.value++ // also updates state.count
console.log(state.count) // 2
</script>computed e watch no Setup
Em <script setup>, computed() e watch() são importados e chamados diretamente. computed cria um ref derivado; watch roda um callback na mudança da fonte. watch pode receber um ref único, um getter, um array de fontes ou um objeto reativo. Estes são os primitivos centrais da Composition API — combine-os para encapsular lógica em composables.
<script setup>
import { ref, computed, watch } from 'vue'
const a = ref(1)
const b = ref(2)
// computed: derived value, cached
const sum = computed(() => a.value + b.value)
// watch: side effect on change
watch(sum, (newSum) => {
console.log('sum changed to', newSum)
})
// watch multiple sources
watch([a, b], ([newA, newB]) => {
console.log('a or b changed:', newA, newB)
})
</script>shallowRef e shallowReactive
shallowRef e shallowReactive abrem mão da reatividade profunda — só a referência/propriedades de topo são rastreadas. Isso melhora drasticamente o desempenho para estruturas de dados grandes (ex.: array de dados de um gráfico, grafo de cena 3D) em que o rastreamento profundo é desperdício. Use triggerRef() para notificar o Vue manualmente após uma mutação profunda. Recorra a estes só quando mediu um problema de desempenho.
<script setup>
import { shallowRef, shallowReactive, triggerRef } from 'vue'
// shallowRef: only .value changes trigger updates
// (deep changes to .value properties do NOT)
const big = shallowRef({ items: [1, 2, 3] })
big.value.items.push(4) // NO update triggered
big.value = { items: [1,2,3,4] } // update triggered
// force update after deep mutation
big.value.items.push(5)
triggerRef(big) // tells Vue to re-render
// shallowReactive: only root-level props are reactive
const state = shallowReactive({ user: { name: 'A' } })
state.count = 1 // reactive
state.user.name = 'B' // NOT reactive
</script>Composables
Escrevendo um Composable
Um composable é uma função que encapsula lógica reativa reutilizável. Por convenção, nomeie-a useAlgo. Usa hooks da Composition API (onMounted etc.), que se vinculam ao ciclo de vida do componente consumidor. Retorne refs e funções. O componente os desestrutura. Composables são o equivalente Vue dos hooks do React — permitem compartilhar lógica com estado sem render props ou HOCs.
<!-- useMousePosition.js -->
import { ref, onMounted, onUnmounted } from 'vue'
export function useMousePosition() {
const x = ref(0)
const y = ref(0)
function update(e) {
x.value = e.pageX
y.value = e.pageY
}
onMounted(() => window.addEventListener('mousemove', update))
onUnmounted(() => window.removeEventListener('mousemove', update))
return { x, y }
}
<!-- In component -->
<script setup>
import { useMousePosition } from './useMousePosition'
const { x, y } = useMousePosition()
</script>Composable com Estado (Estado Compartilhado)
Quando o estado é declarado no escopo do módulo (fora da função), é um singleton — cada um dos componentes usando o composable compartilham o mesmo estado. Esta é uma alternativa leve ao Pinia para estado global simples. Use readonly() para expor estado sem permitir mutação direta — componentes devem chamar login/logout para mudá-lo. Para apps complexos, prefira Pinia (melhores devtools, persistência, suporte a SSR).
<!-- useUser.js -->
import { reactive, readonly } from 'vue'
// module-scoped state — shared across all consumers
const state = reactive({
user: null,
loading: false
})
export function useUser() {
async function login(credentials) {
state.loading = true
state.user = await fetch('/api/login', {
method: 'POST',
body: JSON.stringify(credentials)
}).then(r => r.json())
state.loading = false
}
function logout() {
state.user = null
}
return {
user: readonly(state.user), // expose read-only
loading: readonly(state.loading),
login,
logout
}
}Composable useFetch
Este composable embrulha fetch com estado de carregamento/erro e busca de novo quando uma url reativa muda. isRef() verifica se a entrada é um ref; unref() desembrulha (retorna o valor para refs, identidade caso contrário). Retornar refresh permite que o consumidor busque de novo manualmente. Este padrão (entrada reativa + reexecução automática + expor estado) é o pão e a manteiga dos composables para busca de dados.
<!-- useFetch.js -->
import { ref, watchEffect, isRef, unref } from 'vue'
export function useFetch(url) {
const data = ref(null)
const error = ref(null)
const loading = ref(true)
async function doFetch() {
loading.value = true
error.value = null
try {
const res = await fetch(unref(url))
if (!res.ok) throw new Error('HTTP ' + res.status)
data.value = await res.json()
} catch (e) {
error.value = e.message
} finally {
loading.value = false
}
}
// re-fetch when url ref changes
if (isRef(url)) {
watchEffect(doFetch)
} else {
doFetch()
}
return { data, error, loading, refresh: doFetch }
}Composable com Limpeza
Composables que registram efeitos colaterais (listeners, timers, assinaturas) PRECISAM limpar — tipicamente via onUnmounted dentro do composable. Isso vincula a limpeza ao componente que consumir o composable, para que o consumidor não precise lembrar. Esta é uma grande vantagem dos composables sobre funções utilitárias: participam do ciclo de vida do componente.
<!-- useEventListener.js -->
import { onUnmounted } from 'vue'
export function useEventListener(target, event, callback) {
target.addEventListener(event, callback)
// auto-cleanup when the consuming component unmounts
onUnmounted(() => {
target.removeEventListener(event, callback)
})
}
<!-- Usage -->
<script setup>
import { useEventListener } from './useEventListener'
import { ref } from 'vue'
const key = ref('')
useEventListener(window, 'keydown', (e) => {
key.value = e.key
})
// listener is removed automatically on unmount
</script>Convenções de Composable
Siga estas convenções: (1) nomeie composables com o prefixo use; (2) retorne refs (não valores simples — valores simples perdem reatividade); (3) aceite refs ou getters como entradas, por flexibilidade; (4) use onUnmounted para limpeza; (5) mantenha-os focados (uma preocupação por composable). Essas convenções tornam os composables componíveis entre si e previsíveis de usar.
<!-- DO: name with 'use' prefix, return refs -->
export function useCounter(initial = 0) {
const count = ref(initial)
const inc = () => count.value++
const dec = () => count.value--
return { count, inc, dec }
}
<!-- AVOID: returning plain values (loses reactivity) -->
export function badCounter() {
let count = 0 // plain variable — NOT reactive!
return { count, inc: () => count++ }
}
<!-- DO: accept refs/getters for flexible inputs -->
export function useSearch(query) {
// query can be a ref, a getter, or a plain value
return watchEffect(() => fetch('/api?q=' + unref(query)))
}Imersão em Reatividade
Mecânica de Proxy Reativo
A reatividade do Vue 3 usa Proxy (ES6). reactive() retorna um Proxy que intercepta get (para rastrear dependências) e set (para acionar atualizações). O objeto original não é modificado — você recebe uma versão embrulhada. isReactive() verifica se algo é um proxy reativo. Isso é mais poderoso que a abordagem Object.defineProperty do Vue 2, que não detectava adições de propriedades novas.
<script setup>
import { reactive, isReactive, isProxy } from 'vue'
const state = reactive({ count: 0 })
// reactive() wraps the object in a Proxy
// reads/writes are tracked and trigger updates
state.count++ // triggers re-render
// the original object is NOT reactive
const raw = { count: 0 }
const wrapped = reactive(raw)
console.log(raw === wrapped) // false
console.log(isReactive(wrapped)) // true
console.log(isReactive(raw)) // false
console.log(isProxy(wrapped)) // true
</script>Regras de Desembrulhamento de ref
Regras de desembrulhamento de ref: em <script>, acesse via .value; nos templates e dentro de objetos reativos, refs se desembrulham para o .value. É por isso que {{ count }} num template funciona sem .value. O desembrulhamento automático é raso — refs aninhados em arrays/Maps não desembrulham. Objetos reativos que contêm refs mutam o value do ref ao atribuir: state.count = 5 define count.value = 5.
<script setup>
import { ref, reactive } from 'vue'
const count = ref(0)
const state = reactive({ count })
// in JS: ref needs .value
count.value = 1
// in reactive object: ref auto-unwraps
console.log(state.count) // 1 (not count.value)
state.count = 5 // updates count.value
// in templates: ref auto-unwraps
// {{ count }} renders count.value
</script>
<template>
<p>{{ count }}</p> <!-- 5, not [object Object] -->
</template>Effect e track/trigger (Entranhas)
effect() é o primitivo de baixo nível por trás da reatividade — roda uma função, rastreia toda leitura reativa dentro dela e reexecuta quando qualquer valor rastreado muda. computed, watch, watchEffect e a renderização de componentes se baseiam em effect. Você raramente chama effect() diretamente no código do app — prefira computed/watch/watchEffect — mas é o motor. Entendê-lo ajuda a raciocinar sobre reordenação e tempo.
<script setup>
import { ref, effect } from 'vue'
const count = ref(0)
// effect runs immediately, then re-runs on dep change
effect(() => {
console.log('count is', count.value)
})
// logs: count is 0
count.value = 10
// logs: count is 10
// internally:
// - effect tracks dependencies accessed inside it
// - setting count.value triggers all tracked effects
</script>markRaw e readonly
markRaw() opta um objeto permanentemente fora da reatividade — útil para instâncias de classes de terceiros (gráficos, mapas, estado de jogos) que têm os próprios mecanismos de atualização e não devem ser embrulhadas num Proxy. readonly() cria uma visão somente leitura de um objeto reativo — tentativas de mutação avisam no modo dev. Use readonly para expor estado de composables/stores, prevenindo mutação direta.
<script setup>
import { reactive, markRaw, readonly, isReadonly } from 'vue'
// markRaw: opt a value OUT of reactivity forever
const bigChart = markRaw(new HeavyChartLib())
const state = reactive({ chart: bigChart })
// state.chart mutations won't trigger Vue updates
// (use chart's own API to update it)
// readonly: make a reactive object read-only
const original = reactive({ count: 0 })
const frozen = readonly(original)
frozen.count = 5
// warning: target is readonly (dev mode)
console.log(isReadonly(frozen)) // true
</script>Custom Ref (factory)
customRef() permite controlar explicitamente o rastreamento de dependências e o acionamento. A factory recebe track() e trigger() — chame track() no get() para registrar a dependência, chame trigger() no set() para notificar atualizações. Isso habilita padrões como refs com debounce, refs preguiçosos ou refs apoiados em storage. Poderoso, mas use com parcimônia — geralmente watchEffect + um ref normal é mais claro.
<script setup>
import { customRef } from 'vue'
// debounce a ref's updates
function debouncedRef(value, delay = 200) {
let timeout
return customRef((track, trigger) => ({
get() {
track() // tell Vue this value is a dependency
return value
},
set(newValue) {
clearTimeout(timeout)
timeout = setTimeout(() => {
value = newValue
trigger() // notify Vue of the change
}, delay)
}
}))
}
const text = debouncedRef('', 300)
// input only triggers re-render 300ms after typing stops
</script>Vue Router
Setup do Router
createRouter configura o roteamento. createWebHistory usa o modo history HTML5 (URLs limpos, exige fallback do servidor para index.html). Carregue componentes de rota preguiçosamente com import() dinâmico para code-splitting — cada rota vira seu próprio bundle. Segmentos dinâmicos (:id) são acessados via route.params. Instale o router como plugin com app.use(router).
<!-- router/index.js -->
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'
const routes = [
{ path: '/', name: 'home', component: Home },
{
path: '/about',
name: 'about',
// lazy-load for code-splitting
component: () => import('../views/About.vue')
},
{ path: '/user/:id', name: 'user', component: () => import('../views/User.vue') }
]
export const router = createRouter({
history: createWebHistory(),
routes
})
<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'
import { router } from './router'
createApp(App).use(router).mount('#app')RouterView e RouterLink
<RouterView> é o espaço reservado onde o componente da rota casada renderiza. <RouterLink> renderiza uma tag <a>, mas intercepta cliques para navegação no cliente (sem recarregar a página inteira). A prop to aceita um caminho string ou um objeto ({ name, params, query }). RouterLink adiciona classes active/exact-active para estilizar o link atual.
<!-- App.vue -->
<template>
<nav>
<!-- RouterLink renders <a>, handles navigation -->
<RouterLink to="/">Home</RouterLink>
<RouterLink to="/about">About</RouterLink>
<RouterLink :to="{ name: 'user', params: { id: 42 } }">
User 42
</RouterLink>
</nav>
<!-- matched route's component renders here -->
<RouterView />
</template>Navegação e Roteamento Programático
useRouter() dá a instância do router para navegação; useRoute() dá a rota atual (reativa). push adiciona uma entrada de histórico (botão voltar funciona); replace não. Propriedades da rota (path, params, query, hash, name, matched) são reativas — watchers e computeds reexecutam na navegação. Sempre use router.push para navegação dentro do app — nunca window.location, para mantê-lo SPA.
<script setup>
import { useRouter, useRoute } from 'vue-router'
const router = useRouter()
const route = useRoute()
// push to a new URL (adds to history)
function goHome() {
router.push('/')
router.push({ name: 'user', params: { id: 1 } })
router.push({ path: '/search', query: { q: 'vue' } })
}
// replace current entry (no back button)
router.replace('/login')
// go back/forward
router.back()
router.forward()
router.go(-2)
// access current route info
console.log(route.path, route.params.id, route.query.q)
</script>Route Guards
Guards controlam o fluxo de navegação. O beforeEach global é ótimo para checagens de auth. O beforeEnter por rota protege rotas específicas. Guards no componente (onBeforeRouteLeave, onBeforeRouteUpdate) são úteis para avisos de mudanças não salvas. Retorne false ou uma rota para cancelar/redirecionar; retorne true/undefined para confirmar. Guards assíncronos podem retornar uma Promise. Use route.meta para anexar flags como requiresAuth.
<!-- router/index.js -->
const router = createRouter({ history, routes })
// global guard: runs on every navigation
router.beforeEach((to, from) => {
if (to.meta.requiresAuth && !isAuthenticated()) {
return '/login' // redirect
}
// return true or undefined to confirm
})
// per-route guard
{ path: '/admin', component: Admin, beforeEnter: (to, from) => {
if (!isAdmin()) return '/403'
}}
// in-component guard
<script setup>
import { onBeforeRouteLeave } from 'vue-router'
onBeforeRouteLeave((to, from) => {
if (hasUnsavedChanges()) {
return confirm('Discard changes?')
}
})
</script>Lazy Loading e Rotas Aninhadas
Rotas aninhadas renderizam componentes filhos dentro do <RouterView> do pai. Defina children com caminhos relativos ao pai. Caminho vazio ('') casa exatamente com a URL do pai. O import() dinâmico divide o código de cada rota no próprio bundle. Use route.meta para anexar dados (requisitos de auth, títulos) — acessíveis nos guards via to.meta. Agrupe rotas relacionadas com um comentário de nome de chunk.
const routes = [
{
path: '/dashboard',
component: () => import('../views/Dashboard.vue'),
children: [
{ path: '', component: () => import('../views/Overview.vue') },
{ path: 'stats', component: () => import('../views/Stats.vue') },
{ path: 'settings', component: () => import('../views/Settings.vue') }
]
},
// group routes into one chunk
{
path: '/admin',
component: () => import(/* webpackChunkName: "admin" */ '../views/Admin.vue'),
meta: { requiresAuth: true, role: 'admin' }
}
]Gestão de Estado (Pinia)
Definindo uma Store
Pinia é a gestão de estado oficial do Vue (sucessora do Vuex). defineStore com uma função setup dá a sintaxe da Composition API — ref/computed são state/getters, funções retornadas são actions. O primeiro argumento é um id único da store. Setup stores são flexíveis (você pode usar qualquer composable dentro). Alternativamente, use a sintaxe Options (objeto state/getters/actions) para uma sensação mais parecida com Vuex.
<!-- stores/counter.js -->
import { defineStore } from 'pinia'
// setup syntax (composition API style)
export const useCounterStore = defineStore('counter', () => {
const count = ref(0)
const double = computed(() => count.value * 2)
function increment() {
count.value++
}
function asyncIncrement() {
setTimeout(() => count.value++, 1000)
}
return { count, double, increment, asyncIncrement }
})Usando uma Store
Chame useStore() dentro do setup para acessar uma store. Para desestruturação reativa, use storeToRefs() (como toRefs, mas pula actions). Actions podem ser desestruturadas diretamente — são vinculadas à store. Pinia permite mutação direta (counter.count = 5) e $patch para atualizações em lote. Stores são singletons — a mesma instância em cada um dos componentes. Instale Pinia com app.use(createPinia()).
<script setup>
import { useCounterStore } from '../stores/counter'
import { storeToRefs } from 'pinia'
const counter = useCounterStore()
// state and getters lose reactivity if destructured directly
// use storeToRefs to preserve it
const { count, double } = storeToRefs(counter)
// actions can be destructured directly (they're functions)
const { increment } = counter
// mutate state directly (Pinia allows it, unlike Vuex)
counter.count = 5
counter.$patch({ count: 10 })
counter.$patch(state => { state.count++ })
</script>
<template>
<p>{{ count }} x 2 = {{ double }}</p>
<button @click="increment">+</button>
</template>Getters e Composição de Stores
Getters são valores computados derivados do estado. Para usar outra store dentro de uma, basta chamar o useStore() dela — Pinia cuida da dependência. Isso torna a composição de stores trivial (diferente dos módulos do Vuex). Getters também podem referenciar outros getters. Para operações assíncronas, basta escrever funções async na store — sem contexto especial de 'actions' como no Vuex.
<!-- stores/cart.js -->
import { defineStore } from 'pinia'
import { useUserStore } from './user'
export const useCartStore = defineStore('cart', () => {
const items = ref([])
// getter (computed)
const total = computed(() =>
items.value.reduce((sum, i) => sum + i.price * i.qty, 0)
)
const itemCount = computed(() =>
items.value.reduce((n, i) => n + i.qty, 0)
)
// compose other stores
const userStore = useUserStore()
const canCheckout = computed(() =>
userStore.isLoggedIn && items.value.length > 0
)
function addItem(item) {
items.value.push(item)
}
return { items, total, itemCount, canCheckout, addItem }
})Assinaturas e Persistência
$subscribe dispara em qualquer mudança de estado (com informação de mutação e o novo estado). Use para persistência (localStorage, sessionStorage) ou sincronização com sistemas externos. $onAction engancha chamadas de action — útil para logging, análises ou medir a duração de actions. Os callbacks after/onError permitem reagir à conclusão ou falha de actions. A limpeza acontece automaticamente ao desmontar o componente.
<script setup>
import { useCartStore } from '../stores/cart'
const cart = useCartStore()
// subscribe to any state change
cart.$subscribe((mutation, state) => {
console.log('cart changed', mutation.type, state)
// persist to localStorage
localStorage.setItem('cart', JSON.stringify(state.items))
})
// subscribe to actions
cart.$onAction(({ name, after, onError }) => {
console.log('action started:', name)
after(result => console.log('action done:', name, result))
onError(err => console.error('action failed:', name, err))
})
</script>Reset e Módulos de Store
Stores de sintaxe Options têm $reset() embutido; setup stores não — implemente reset() manualmente reatribuindo cada ref. Pinia é modular por design — cada store é independente, sem módulos aninhados como no Vuex. Componha stores chamando useOutraStore() dentro de uma. Instale Pinia globalmente com createPinia(). Stores são tree-shakables e têm excelente suporte a TypeScript e integração com devtools.
<!-- stores/user.js -->
import { defineStore } from 'pinia'
export const useUserStore = defineStore('user', () => {
const name = ref('')
const isLoggedIn = ref(false)
function login(n) { name.value = n; isLoggedIn.value = true }
function logout() { name.value = ''; isLoggedIn.value = false }
// Pinia setup stores don't have a built-in $reset
// implement it manually
function reset() {
name.value = ''
isLoggedIn.value = false
}
return { name, isLoggedIn, login, logout, reset }
})
<!-- main.js -->
import { createPinia } from 'pinia'
const pinia = createPinia()
app.use(pinia)Transições e Animação
Componente Transition
Envolva um elemento v-if/v-show em <Transition> para animar entrada/saída. O Vue adiciona 6 classes nos momentos certos: *-enter-from (estado inicial), *-enter-active (durante a transição), *-enter-to (estado final) e *-leave-*. Defina transições/animações CSS nessas classes. A prop name troca o prefixo 'v-'. Só um elemento filho é permitido; para listas use TransitionGroup.
<template>
<Transition name="fade">
<p v-if="show">Hello</p>
</Transition>
</template>
<style>
/* 6 classes: {name}-enter-{from,active,to}, {name}-leave-{...} */
.fade-enter-active, .fade-leave-active {
transition: opacity 0.3s ease;
}
.fade-enter-from, .fade-leave-to {
opacity: 0;
}
</style>Modos e Hooks de Transição
mode='out-in' anima totalmente o elemento que sai antes do que entra começar — perfeito para trocar componentes (abas) sem sobreposição. mode='in-out' é raramente usado. Hooks JavaScript (@before-enter, @enter, @leave) permitem dirigir animações com bibliotecas como GSAP. Defina :css='false' para dizer ao Vue para pular a detecção de CSS e confiar só nos seus hooks JS (pequeno ganho de desempenho).
<template>
<!-- 'out-in': current leaves, then new enters -->
<Transition mode="out-in" name="fade">
<component :is="currentTab" />
</Transition>
<!-- JavaScript hooks for GSAP/anime.js -->
<Transition
@before-enter="beforeEnter"
@enter="enter"
@leave="leave"
:css="false"
>
<div v-if="show">Animated</div>
</Transition>
</template>TransitionGroup para Listas
TransitionGroup anima listas v-for com três comportamentos: entrada (item novo), saída (item removido) e movimento (item existente mudando de posição). A classe *-move anima a técnica FLIP — o Vue computa deltas de posição e aplica uma transição de transform. Defina position: absolute em leave-active para que o item que sai saia do fluxo, deixando os irmãos deslizarem suavemente ao lugar.
<template>
<TransitionGroup name="list" tag="ul">
<li v-for="item in items" :key="item.id">{{ item.text }}</li>
</TransitionGroup>
</template>
<style>
.list-enter-active, .list-leave-active { transition: all 0.5s; }
.list-enter-from, .list-leave-to { opacity: 0; transform: translateX(30px); }
/* the magic class for reordering */
.list-leave-active { position: absolute; }
.list-move { transition: transform 0.5s ease; }
</style>Estado Animado com Wrapper <Transition>
Você pode sobrescrever os nomes de classe padrão do Vue com personalizados — enter-active-class e leave-active-class. Isso permite plugá-lo a sistemas de animação existentes (Animate.css, utilitários de animação do Tailwind, keyframes personalizados). O padrão: defina sua animação numa classe e aponte a transition do Vue para ela. Isso faz a ponte entre o ciclo de vida do Vue e qualquer framework de animação CSS.
<template>
<button @click="show = !show">Toggle</button>
<Transition
enter-active-class="animate__animated animate__fadeIn"
leave-active-class="animate__animated animate__fadeOut"
>
<div v-if="show" class="box">Content</div>
</Transition>
</template>
<!-- combine with third-party animation libraries -->
<!-- Animate.css, Tailwind animations, custom keyframes -->Suspense para Async
Suspense coordena setup assíncrono — quando um componente filho usa await de nível superior, ele suspende, e Suspense mostra o #fallback. Uma vez que cada um dos filhos assíncronos resolvem, o slot padrão renderiza. Elegante para componentes de busca de dados. Nota: Suspense ainda é experimental no Vue 3 — o tratamento de erros exige onErrorCaptured. Para produção, a maioria das equipes ainda usa composables + estado de carregamento.
<template>
<Suspense>
<template #default>
<AsyncComponent />
</template>
<template #fallback>
<div>Loading...</div>
</template>
</Suspense>
</template>
<!-- AsyncComponent uses top-level await -->
<script setup>
import { ref } from 'vue'
const data = ref(null)
// top-level await suspends the component
const res = await fetch('/api/data').then(r => r.json())
data.value = res
</script>Teleport e Suspense
Básico de Teleport
Teleport renderiza conteúdo num elemento DOM em outro lugar do documento (frequentemente no nível do body), mas o componente mantém o contexto reativo, props, emits etc. do pai. Isso resolve problemas de z-index/overflow com modais, tooltips e dropdowns que seriam cortados por overflow:hidden ou contextos de empilhamento dos pais. O seletor 'to' mira o elemento de destino.
<!-- Modal.vue -->
<template>
<!-- the rendered content is moved to #modals in the DOM,
but keeps the component's reactive context -->
<Teleport to="#modals">
<div class="modal">
<h2>{{ title }}</h2>
<slot />
<button @click="$emit('close')">Close</button>
</div>
</Teleport>
</template>
<!-- index.html must have -->
<!-- <div id="app"></div> -->
<!-- <div id="modals"></div> -->Teleport Condicional
A prop disabled permite teleportar condicionalmente — quando true, o conteúdo renderiza no próprio lugar (sem teleportar). Útil quando o mesmo componente é usado em contextos diferentes (ex.: um tooltip que deve ser teleportado num layout normal, mas inline dentro de outro modal). Múltiplos Teleports mirando o mesmo elemento se anexam na ordem de renderização. Teleport funciona com v-if dentro dele.
<template>
<!-- disabled: render in place (not teleported) -->
<Teleport :to="target" :disabled="inline">
<div class="popup" v-if="show">...</div>
</Teleport>
</template>
<script setup>
const props = defineProps({
inline: Boolean // if true, render inline instead of teleporting
})
const target = '#popups'
</script>
<!-- Multiple Teleports to same target: appended in order -->Teleport para Modais e Notificações
Teleportar para o body é o padrão para modais — o modal escapa de quaisquer restrições de overflow/transform/z-index dos pais. Combine com Transition para animação de entrada/saída. O @click.self no backdrop fecha ao clicar fora (mas não no conteúdo). Slots deixam o pai personalizar totalmente o header, o corpo e o footer do modal, enquanto o componente de modal cuida do posicionamento e da animação.
<!-- components/Modal.vue -->
<template>
<Teleport to="body">
<Transition name="modal">
<div v-if="show" class="modal-backdrop" @click.self="$emit('close')">
<div class="modal-content">
<header><slot name="header" /></header>
<slot />
<footer><slot name="footer" /></footer>
</div>
</div>
</Transition>
</Teleport>
</template>Suspense com Setup Assíncrono
Quando o setup de um componente filho usa await de nível superior, retorna uma Promise. Suspense a captura e mostra o #fallback até a resolução. O resultado do setup do componente suspenso é então usado para renderizar. Múltiplos filhos assíncronos são coordenados — Suspense espera cada filho. onErrorCaptured captura erros de setup. Suspense ainda é experimental — para produção, prefira estado de carregamento manual em composables.
<!-- Parent.vue -->
<template>
<Suspense>
<AsyncProfile :id="userId" />
<template #fallback>
<Spinner />
</template>
</Suspense>
</template>
<!-- AsyncProfile.vue -->
<script setup>
const props = defineProps(['id'])
// top-level await suspends this component
const profile = await fetch(`/api/users/${props.id}`).then(r => r.json())
// component only renders after this resolves
</script>Suspense Aninhado e Componentes Assíncronos
Suspense pode ser aninhado — cada nível trata a própria fronteira assíncrona. O Suspense externo mostra PageSkeleton enquanto o Dashboard (e tudo que ele precisa) carrega; o interno mostra ChartSkeleton especificamente para o gráfico. Esse carregamento granular melhora a UX: a casca da página aparece primeiro, depois as seções individuais preenchem. Lembre que Suspense é experimental — teste bem e trate erros via onErrorCaptured.
<template>
<Suspense>
<template #default>
<Dashboard>
<Suspense>
<template #default>
<AsyncChart :data="data" />
</template>
<template #fallback>
<ChartSkeleton />
</template>
</Suspense>
</Dashboard>
</template>
<template #fallback>
<PageSkeleton />
</template>
</Suspense>
</template>Provide / Inject
Provide e Inject Básicos
provide() torna um valor disponível a cada um dos componentes descendentes; inject() o recupera em qualquer lugar abaixo na árvore. Isso evita a perfuração de props para componentes profundamente aninhados. O segundo argumento do inject é um valor padrão (usado se nada for fornecido). Refs fornecidos são reativos — descendentes podem mutá-los e o pai vê as mudanças. Use chaves Symbol para evitar colisões em apps grandes.
<!-- Parent.vue -->
<script setup>
import { provide, ref } from 'vue'
const theme = ref('dark')
const user = ref({ name: 'Alice' })
// provide to all descendants
provide('theme', theme)
provide('user', user)
</script>
<!-- DeepChild.vue (any level of nesting) -->
<script setup>
import { inject } from 'vue'
const theme = inject('theme', 'light') // default 'light'
const user = inject('user')
// these are reactive refs, just like in the parent
</script>Estado Fornecido Somente Leitura
Use readonly() para expor estado sem permitir mutação direta — descendentes devem chamar as funções de action fornecidas para mudá-lo. Este padrão (ref mutável privado + visão pública readonly + funções de action) é uma alternativa leve ao Pinia para estado com escopo na árvore de componentes. Impõe fluxo de dados unidirecional e previne bugs de mutações aleatórias profundas na árvore.
<!-- store.js (shared composable) -->
import { ref, readonly } from 'vue'
const _count = ref(0) // private mutable state
export function useCountStore() {
return {
count: readonly(_count), // consumers can't mutate
increment: () => _count.value++ // only via action
}
}
<!-- Provider.vue -->
<script setup>
import { provide } from 'vue'
import { useCountStore } from './store'
const store = useCountStore()
provide('countStore', store)
</script>Chaves de Injeção Tipadas
Use InjectionKey<Ref<Tipo>> para criar uma chave de símbolo tipada. Isso dá inferência completa de TypeScript — inject conhece o tipo de retorno. Chaves Symbol evitam colisões de string quando múltiplas bibliotecas fornecem valores. Para singletons de app inteiro, prefira Pinia a provide/inject — Pinia tem devtools, persistência e melhor testabilidade. Use provide/inject para contexto com escopo na árvore de componentes (tema, formulário, locale).
<!-- keys.ts -->
import type { InjectionKey, Ref } from 'vue'
import { inject, provide } from 'vue'
export const ThemeKey: InjectionKey<Ref<string>> = Symbol('theme')
<!-- Provider.vue -->
<script setup>
import { ref } from 'vue'
import { ThemeKey } from './keys'
const theme = ref('dark')
provide(ThemeKey, theme)
</script>
<!-- Consumer.vue -->
<script setup>
import { inject } from 'vue'
import { ThemeKey } from './keys'
// TS knows theme is Ref<string> | undefined
const theme = inject(ThemeKey)
// with default
const theme2 = inject(ThemeKey, ref('light'))
</script>Atualizando Valores Fornecidos
O padrão recomendado: forneça um objeto contendo o estado reativo E as funções para mutá-lo. Isso mantém a API explícita e previne mutações aleatórias. Filhos desestruturam o estado e as actions. Isso é essencialmente uma mini-store — para qualquer coisa além de poucos valores, considere um composable que retorna a mesma forma, ou Pinia. O valor fornecido é reativo porque contém um ref.
<!-- Provider.vue -->
<script setup>
import { ref, provide } from 'vue'
const count = ref(0)
// expose value + mutator together
provide('counter', {
count, // reactive ref
increment: () => count.value++,
reset: () => count.value = 0
})
</script>
<!-- DeepChild.vue -->
<script setup>
import { inject } from 'vue'
const { count, increment, reset } = inject('counter')
// count is reactive, increment/reset are actions
</script>
<template>
<p>{{ count }}</p>
<button @click="increment">+</button>
<button @click="reset">Reset</button>
</template>Provide no Nível do App
app.provide() torna um valor disponível a cada componente do app — útil para constantes de app inteiro (URLs de API, feature flags, config de ambiente). Diferente do provide no nível do componente, isto não é reativo por padrão (a menos que você forneça um ref). É uma boa forma de injetar config específica de ambiente sem importar arquivos de env em qualquer lugar. Combine com inject() em qualquer componente para acessar essas globais.
<!-- main.js -->
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
// app-level provide — available to ALL components
app.provide('apiUrl', 'https://api.example.com')
app.provide('apiKey', import.meta.env.VITE_API_KEY)
// useful for app-wide constants
app.provide('features', {
darkMode: true,
beta: false
})
app.mount('#app')Snippets de Vue 3 relacionados
Copy-paste ready code for common tasks.
Single-File Component
Define a Vue 3 component with script setup, template, and scoped styles.
Composition API
Organize reactive state, computed, and lifecycle logic by feature.
Refs & Reactive
Choose between ref and reactive for reactive state.
Computed & Watch
Derive values with computed and react to changes with watch.
Props & Emits
Declare inputs and events, and implement v-model on a component.
Lifecycle Hooks
Register lifecycle callbacks as composable functions.
Slots & Scoped Slots
Distribute content with default, named, and scoped slots.
Composables
Extract reusable reactive logic into a useMouse composable.
Was this helpful?