---
title: "How to read the Vue docs (and when not to) · vuejs.school"
description: "A map of vuejs.org, a method for reading an API page, and a worked example that turns the watch flush option from jargon into a decision."
canonical_url: "https://vuejs.school/community/blog/how-to-read-the-vue-docs"
meta:
  "og:description": "A map of vuejs.org, a method for reading an API page, and a worked example that turns the watch flush option from jargon into a decision."
  "og:image": "https://vuejs.school/_og/d/a_~SG93IHRvIHJlYWQgdGhlIFZ1ZSBkb2NzIChhbmQgd2hlbiBub3QgdG8pIMK3IHZ1ZWpzLnNjaG9vbA%2Cc_OgCard.takumi%2Ctitle_How%2Bto%2Bread%2Bthe%2BVue%2Bdocs%2B(and%2Bwhen%2Bnot%2Bto)%2Cdescription_~QSBtYXAgb2YgdnVlanMub3JnLCBhIG1ldGhvZCBmb3IgcmVhZGluZyBhbiBBUEkgcGFnZSwgYW5kIGEgd29ya2VkIGV4YW1wbGUgdGhhdCB0dXJucyB0aGUgd2F0Y2ggZmx1c2ggb3B0aW9uIGZyb20gamFyZ29uIGludG8gYSBkZWNpc2lvbi4%2Ceyebrow_~TGVhcm5pbmcgdGlwcyDCtyA3IG1pbiByZWFk%2Ctint_sand%2Cp_Ii9jb21tdW5pdHkvYmxvZy9ob3ctdG8tcmVhZC10aGUtdnVlLWRvY3Mi%2Cs_phQzxtIza68dq65q.png"
  "og:image:alt": "How to read the Vue docs (and when not to) · vuejs.school"
  "og:image:height": "600"
  "og:image:type": image/png
  "og:image:width": "1200"
  "og:title": "How to read the Vue docs (and when not to) · vuejs.school"
  "twitter:image": "https://vuejs.school/_og/d/a_~SG93IHRvIHJlYWQgdGhlIFZ1ZSBkb2NzIChhbmQgd2hlbiBub3QgdG8pIMK3IHZ1ZWpzLnNjaG9vbA%2Cc_OgCard.takumi%2Ctitle_How%2Bto%2Bread%2Bthe%2BVue%2Bdocs%2B(and%2Bwhen%2Bnot%2Bto)%2Cdescription_~QSBtYXAgb2YgdnVlanMub3JnLCBhIG1ldGhvZCBmb3IgcmVhZGluZyBhbiBBUEkgcGFnZSwgYW5kIGEgd29ya2VkIGV4YW1wbGUgdGhhdCB0dXJucyB0aGUgd2F0Y2ggZmx1c2ggb3B0aW9uIGZyb20gamFyZ29uIGludG8gYSBkZWNpc2lvbi4%2Ceyebrow_~TGVhcm5pbmcgdGlwcyDCtyA3IG1pbiByZWFk%2Ctint_sand%2Cp_Ii9jb21tdW5pdHkvYmxvZy9ob3ctdG8tcmVhZC10aGUtdnVlLWRvY3Mi%2Cs_phQzxtIza68dq65q.png"
  "twitter:image:alt": "How to read the Vue docs (and when not to) · vuejs.school"
---

> Index of every page on this site: [llms.txt](https://vuejs.school/llms.txt)

## Find your way around vuejs.org

Five parts of the site matter while you learn, and knowing which one you are in tells you how to read it.

The **Guide** is the book. Its left sidebar runs from Getting Started and Essentials through Components In-Depth, Reusability, Built-in Components, Scaling Up, Best Practices and TypeScript to Extra Topics. Essentials covers the core: creating an app, template syntax, reactivity, computed properties, class bindings, conditionals, lists, events, forms, watchers, template refs, components basics and lifecycle hooks. Read it top to bottom once; later, come back to single pages.

The **Tutorial** is a short, interactive walk through the basics with an editor beside the text. The **Examples** page holds small complete apps in three groups: Basic, Practical (among them a Markdown editor, fetching data, a sortable grid, a tree view and a modal with transitions) and the 7 GUIs tasks.

The **API reference** is the dictionary. It is organised by kind: Global API, Composition API, Options API, Built-ins (directives, components, special elements and attributes), Single-File Component and Advanced APIs. The index page has a filter box. Typing `watch` narrows it to `watch()`, `watchEffect()`, `watchPostEffect()`, `watchSyncEffect()` and `onWatcherCleanup()` under Composition API, plus the `watch` option and the `$watch()` instance method under Options API.

The **Playground** at play.vuejs.org runs Vue in the browser with nothing to install. It is where you check that you understood a page. It keeps the whole example in the page address, and its share button copies that link, which is how you ask a precise question in the Vue Discord or in a GitHub issue.

## Check the API preference switch

At the top of the Guide's left sidebar, a menu labelled API Preference holds a switch between Options and Composition. The Guide shows its code in the chosen style, and some pages change their prose too. Composition is the default, but your browser remembers a change: click Options once to compare, and it stays there.

If you write `<script setup>` while the docs show Options code, much of what you read will not match your code, and you will think the docs are wrong. So check that the switch says Composition. The Tutorial and the Examples have the same switch, plus a second one for HTML versus SFC (single-file component); keep that on SFC, its default, since a Vite project uses `.vue` files.

The Introduction page discusses the choice under "Which to Choose?". For learning, it says to pick whichever style looks easier to you. For production, it recommends the Composition API with single-file components for full applications, and the Options API without build tools or for simple jobs such as adding interactivity to server-rendered pages. If you are learning to build apps with Vite, Composition matches the code you will write.

## Read an API page in the right order

Most entries in the API reference are laid out the same way, in this order:

- A one or two sentence summary of what the function does.
- **Type**: the TypeScript signature, often with the options and their defaults in comments.
- **Details**: prose that explains the behaviour, the options and the edge cases.
- **Example**: small snippets, often one per variation.
- **See also**: links to the Guide pages that teach the idea.

You do not have to read them top to bottom. This order is faster:

1. Read the summary.
2. Jump to the example that looks like your situation. It tells you whether you are on the right page at all.
3. Read the Type block. It gives the options with their types and usually their defaults, in a few lines, with no prose to misread.
4. Read Details when the Type block raised a question. That is where the answers to "but what if" live.

If the page still feels abstract, follow the See also link to the Guide, which is written to be read without prior knowledge.

## Worked example: the watch flush option

Here is the method applied to a real question. You have a list, you add an item, and you want to scroll the new item into view. A `watch` on the list runs, but the element is not there yet when it runs. Why, and what do you do?

Open the API reference, filter for `watch`, and read the Type block for `watch()`. The interface that lists its options reads:

```
interface WatchOptions extends WatchEffectOptions {
  immediate?: boolean // default: false
  deep?: boolean | number // default: false
  flush?: 'pre' | 'post' | 'sync' // default: 'pre'
  onTrack?: (event: DebuggerEvent) => void
  onTrigger?: (event: DebuggerEvent) => void
  once?: boolean // default: false (3.4+)
}
```

So the option is `flush`, it has three values, and the default is `'pre'`. The `(3.4+)` after `once` means it arrived in Vue 3.4; elsewhere the docs mark newer APIs with a badge such as 3.5+.

The Details section for `watch()` says `flush` adjusts the callback's flush timing and links to `watchEffect()`, whose Details explain the three values:

- `'pre'`, the default: watchers run just before the component renders.
- `'post'`: the watcher waits until after the component has rendered.
- `'sync'`: the watcher runs as soon as a dependency changes. The docs say to use it with caution, because it can cause performance and data-consistency problems when several properties change at the same time.

That is the whole answer. With `'pre'` timing, your callback runs before Vue has added the new `<li>` to the page. The list's last element is still the previous message (or nothing, the first time), so the scroll always lands one item short. You want `'post'`.

Here is the fix as a component you can run. The button and the short `max-height` are only there so you can see the list scroll:

*components/MessageList.vue*

```
<script setup lang="ts">
import { ref, useTemplateRef, watch } from 'vue'

const messages = ref<string[]>([])
const list = useTemplateRef<HTMLUListElement>('list')

function addMessage() {
  messages.value.push(`Message ${messages.value.length + 1}`)
}

watch(
  () => messages.value.length,
  () => list.value?.lastElementChild?.scrollIntoView({ block: 'nearest' }),
  { flush: 'post' },
)
</script>

<template>
  <button type="button" @click="addMessage">Add a message</button>
  <ul ref="list" class="list">
    <li v-for="(message, i) in messages" :key="i">{{ message }}</li>
  </ul>
</template>

<style scoped>
.list {
  max-height: 8rem;
  overflow-y: auto;
}
</style>
```

`useTemplateRef('list')`, new in Vue 3.5, gives you the `<ul>` that has `ref="list"`. The watcher's source is the number of messages, and `flush: 'post'` runs the callback after Vue has updated the list, so `lastElementChild` is the message you just added.

The `watch()` page's own example puts `flush: 'post'` in exactly this place, the third argument. Its See also link leads to the Guide's Watchers page, which explains the same idea under "Callback Flush Timing". Total time: about two minutes, and you now understand the option rather than having copied a line.

## Choose the docs, a tutorial or the source

The docs work best when you know what you are looking for. Match the tool to the question.

**You have a specific question: use the API reference.** "Can `watch` take an array of sources?" Filter, read the Type block, done: the second signature takes `sources: WatchSource<T>[]`. Do not watch a video for this.

**You have no mental model yet: use a tutorial.** If you do not know whether your problem is about props, events or reactivity, you cannot filter the API index, and a Guide page read cold is a list of facts with nothing to attach them to. Use the interactive Tutorial, or a lesson that builds one idea with an example you can run and asks you questions afterwards. Come back to the docs when you can name the thing you need.

**The behaviour is not documented: read the source.** Sometimes you need to know why a warning appears, or in what order two hooks fire in an edge case, and the docs are silent. Vue is open source, and the code that runs components and their lifecycle hooks lives in the `packages/runtime-core/src` folder of the `vuejs/core` repository on GitHub. Searching the repository for a few words of a warning message usually takes you to the line that prints it, and the code around it is the real answer. You will not do this often, and it is a good skill to have before you need it under pressure.

## Read one Guide page per session

Reading documentation is a skill, and like the rest of Vue it improves with short, regular practice. One Guide page per session, in order, is enough. For each page:

1. Open the Playground beside it.
2. Type the example yourself rather than pasting it.
3. Change one thing and predict the result before you run it.

Bookmark the API index and the Playground: once the Guide is behind you, those are the two pages you will open most. When a page links to another under See also, follow the link once. That is how the pieces connect into a picture.

**Was this helpful?**

## **Keep reading**

[Learning tips · 6 min read**Why your quiz brings old questions back**](https://vuejs.school/community/blog/why-your-quiz-brings-old-questions-back) [Learning tips · 7 min read**Finished a track? Here is how to keep the knowledge**](https://vuejs.school/community/blog/finished-a-track-how-to-keep-the-knowledge)

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://vuejs.school/#website","@type":"WebSite","description":"A free AI-instructed school for Vue.js. Short tutorials, runnable code and quizzes that adapt to you.","name":"vuejs.school","url":"https://vuejs.school/","publisher":{"@id":"https://vuejs.school/#identity"}},{"@id":"https://vuejs.school/community/blog/how-to-read-the-vue-docs#webpage","@type":"WebPage","dateModified":"2026-10-27T19:31:40.253Z","datePublished":"2025-06-24","description":"A map of vuejs.org, a method for reading an API page, and a worked example that turns the watch flush option from jargon into a decision.","name":"How to read the Vue docs (and when not to)","url":"https://vuejs.school/community/blog/how-to-read-the-vue-docs","breadcrumb":{"@id":"https://vuejs.school/community/blog/how-to-read-the-vue-docs#breadcrumb"},"isPartOf":{"@id":"https://vuejs.school/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://vuejs.school/community/blog/how-to-read-the-vue-docs"]}],"primaryImageOfPage":{"@id":"https://vuejs.school/#logo"}},{"@id":"https://vuejs.school/#identity","@type":"Organization","description":"A free AI-instructed school for Vue.js. Short tutorials, runnable code and quizzes that adapt to you.","name":"vuejs.school","url":"https://vuejs.school","logo":{"@id":"https://vuejs.school/#logo"}},{"@id":"https://vuejs.school/community/blog/how-to-read-the-vue-docs#article","dateModified":"2026-10-27T19:31:40.253Z","datePublished":"2025-06-24","description":"A map of vuejs.org, a method for reading an API page, and a worked example that turns the watch flush option from jargon into a decision.","headline":"How to read the Vue docs (and when not to)","inLanguage":"en","isAccessibleForFree":true,"thumbnailUrl":"https://vuejs.school/_og/d/a_~SG93IHRvIHJlYWQgdGhlIFZ1ZSBkb2NzIChhbmQgd2hlbiBub3QgdG8pIMK3IHZ1ZWpzLnNjaG9vbA%2Cc_OgCard.takumi%2Ctitle_How%2Bto%2Bread%2Bthe%2BVue%2Bdocs%2B(and%2Bwhen%2Bnot%2Bto)%2Cdescription_~QSBtYXAgb2YgdnVlanMub3JnLCBhIG1ldGhvZCBmb3IgcmVhZGluZyBhbiBBUEkgcGFnZSwgYW5kIGEgd29ya2VkIGV4YW1wbGUgdGhhdCB0dXJucyB0aGUgd2F0Y2ggZmx1c2ggb3B0aW9uIGZyb20gamFyZ29uIGludG8gYSBkZWNpc2lvbi4%2Ceyebrow_~TGVhcm5pbmcgdGlwcyDCtyA3IG1pbiByZWFk%2Ctint_sand%2Cp_Ii9jb21tdW5pdHkvYmxvZy9ob3ctdG8tcmVhZC10aGUtdnVlLWRvY3Mi%2Cs_phQzxtIza68dq65q.png","@type":["Article","BlogPosting"],"articleSection":["Learning tips"],"author":{"@id":"https://vuejs.school/#identity"},"image":{"@id":"https://vuejs.school/#/schema/image/1"},"isPartOf":{"@id":"https://vuejs.school/community/blog/how-to-read-the-vue-docs#webpage"},"mainEntityOfPage":{"@id":"https://vuejs.school/community/blog/how-to-read-the-vue-docs#webpage"},"publisher":{"@id":"https://vuejs.school/#identity"}},{"@id":"https://vuejs.school/community/blog/how-to-read-the-vue-docs#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","name":"Blog","item":"https://vuejs.school/community/blog","position":1},{"@type":"ListItem","name":"How to read the Vue docs (and when not to)","position":2}]},{"@id":"https://vuejs.school/#logo","@type":"ImageObject","caption":"vuejs.school","contentUrl":"https://vuejs.school/apple-touch-icon.png","inLanguage":"en","url":"https://vuejs.school/apple-touch-icon.png"},{"@id":"https://vuejs.school/#/schema/image/1","@type":"ImageObject","contentUrl":"https://vuejs.school/_og/d/a_~SG93IHRvIHJlYWQgdGhlIFZ1ZSBkb2NzIChhbmQgd2hlbiBub3QgdG8pIMK3IHZ1ZWpzLnNjaG9vbA%2Cc_OgCard.takumi%2Ctitle_How%2Bto%2Bread%2Bthe%2BVue%2Bdocs%2B(and%2Bwhen%2Bnot%2Bto)%2Cdescription_~QSBtYXAgb2YgdnVlanMub3JnLCBhIG1ldGhvZCBmb3IgcmVhZGluZyBhbiBBUEkgcGFnZSwgYW5kIGEgd29ya2VkIGV4YW1wbGUgdGhhdCB0dXJucyB0aGUgd2F0Y2ggZmx1c2ggb3B0aW9uIGZyb20gamFyZ29uIGludG8gYSBkZWNpc2lvbi4%2Ceyebrow_~TGVhcm5pbmcgdGlwcyDCtyA3IG1pbiByZWFk%2Ctint_sand%2Cp_Ii9jb21tdW5pdHkvYmxvZy9ob3ctdG8tcmVhZC10aGUtdnVlLWRvY3Mi%2Cs_phQzxtIza68dq65q.png","inLanguage":"en","url":"https://vuejs.school/_og/d/a_~SG93IHRvIHJlYWQgdGhlIFZ1ZSBkb2NzIChhbmQgd2hlbiBub3QgdG8pIMK3IHZ1ZWpzLnNjaG9vbA%2Cc_OgCard.takumi%2Ctitle_How%2Bto%2Bread%2Bthe%2BVue%2Bdocs%2B(and%2Bwhen%2Bnot%2Bto)%2Cdescription_~QSBtYXAgb2YgdnVlanMub3JnLCBhIG1ldGhvZCBmb3IgcmVhZGluZyBhbiBBUEkgcGFnZSwgYW5kIGEgd29ya2VkIGV4YW1wbGUgdGhhdCB0dXJucyB0aGUgd2F0Y2ggZmx1c2ggb3B0aW9uIGZyb20gamFyZ29uIGludG8gYSBkZWNpc2lvbi4%2Ceyebrow_~TGVhcm5pbmcgdGlwcyDCtyA3IG1pbiByZWFk%2Ctint_sand%2Cp_Ii9jb21tdW5pdHkvYmxvZy9ob3ctdG8tcmVhZC10aGUtdnVlLWRvY3Mi%2Cs_phQzxtIza68dq65q.png"}]}
```