Suggest an edit

Improve this article

Refine the answer for “What does the `deep` option do?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

The `deep` option in `watch()` turns on **deep tracking of a reactive object**, meaning Vue reacts **to changes in any nested property**, not just to a change of the object's reference.

In other words:

> `deep: true` **lets you track changes inside an object or array, even when a nested property changes.**

---

## Why aren't nested changes tracked without `deep`?

By default, `watch(obj)` tracks **only the reference**:

```js
const user = reactive({ name: 'Alex', info: { age: 25 } })

watch(user, () => {
  console.log('user changed')
})
```

Calls the handler **only if the whole object is replaced**:

```js
user = { ... }  // Yes
user.info.age = 30 // the handler does NOT fire
```

---

## What does deep: true do?

```js
watch(
  user,
  () => console.log('something inside user changed'),
  { deep: true }
)
```

Now the handler fires on:

- `user.name = 'John'`
- `user.info.age = 26`
- `user.info = { ... }`
- `user.newField = ...`
- a change to an array inside user
- any nested change

---

## Example: watching a form

```js
const form = reactive({
  name: '',
  address: {
    city: '',
    street: ''
  }
})

watch(
  form,
  () => console.log('the form changed'),
  { deep: true }
)
```

Changing:

```js
form.address.city = 'Paris'
```

triggers the watcher - **because of deep: true**.

---

## When to use deep: true?

#### 1. For complex forms

```js
watch(form, saveToLocalStorage, { deep: true })
```

#### 2. For nested objects

```js
watch(settings, applyChanges, { deep: true })
```

#### 3. For arrays and the objects inside them

```js
watch(items, handleChange, { deep: true })
```

#### 4. For "global" settings where anything might change

---

## Important nuances

### 1. Deep watch can be expensive

Vue recursively walks the object to track all its fields.

Avoid using deep on huge objects.

---

### 2. Prefer watching specific fields when possible

Instead of:

```js
watch(filters, doSomething, { deep: true })
```

Prefer:

```js
watch(() => filters.query, doSomething)
```

---

### 3. `watchEffect` is automatically "deep"

But there's no control over its dependencies.

---

## Summary (ideal for an interview)

> `deep: true` **turns on deep tracking of an object.**
> **Vue reacts to a change in any nested property, not just a change of reference.**
> **Useful for forms, settings, arrays, and complex objects, but can be expensive in terms of performance.**

Markdown · drag & drop images · ⌘B / ⌘I shortcuts398 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.