diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 22249e30f3..321b4c64d9 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -69,7 +69,8 @@ const sidebar = {
'/api/options-misc'
]
},
- '/api/instance-properties.md'
+ '/api/instance-properties.md',
+ '/api/instance-methods.md'
]
}
diff --git a/src/api/instance-methods.md b/src/api/instance-methods.md
new file mode 100644
index 0000000000..21482fa45c
--- /dev/null
+++ b/src/api/instance-methods.md
@@ -0,0 +1,277 @@
+# Instance Methods
+
+## $watch
+
+- **Arguments:**
+
+ - `{string | Function} source`
+ - `{Function | Object} callback`
+ - `{Object} [options]`
+ - `{boolean} deep`
+ - `{boolean} immediate`
+
+- **Returns:** `{Function} unwatch`
+
+- **Usage:**
+
+ Watch an expression or a computed function on the Vue instance for changes. The callback gets called with the new value and the old value. The expression only accepts dot-delimited paths. For more complex expressions, use a function instead.
+
+- **Example:**
+
+ ```js
+ const app = Vue.createApp({
+ data() {
+ return {
+ a: 1,
+ b: 2
+ }
+ },
+ created() {
+ // keypath
+ this.$watch('a', (newVal, oldVal) => {
+ // do something
+ })
+
+ // function
+ this.$watch(
+ // every time the expression `this.a + this.b` yields a different result,
+ // the handler will be called. It's as if we were watching a computed
+ // property without defining the computed property itself
+ () => this.a + this.b,
+ (newVal, oldVal) => {
+ // do something
+ }
+ )
+ }
+ })
+ ```
+
+ When watched value is an Object or Array, any changes to its properties or elements won't trigger the watcher because they reference the same Object/Array:
+
+ ```js
+ const app = Vue.createApp({
+ data() {
+ return {
+ article: {
+ text: 'Vue is awesome!'
+ },
+ comments: ['Indeed!', 'I agree']
+ }
+ },
+ created() {
+ this.$watch('article', () => {
+ console.log('Article changed!')
+ })
+
+ this.$watch('comments', () => {
+ console.log('Comments changed!')
+ })
+ },
+ methods: {
+ // These methods won't trigger a watcher because we changed only a property of Object/Array,
+ // not the Object/Array itself
+ changeArticleText() {
+ this.article.text = 'Vue 3 is awesome'
+ },
+ addComment() {
+ this.comments.push('New comment')
+ },
+
+ // These methods will trigger a watcher because we replaced Object/Array completely
+ changeWholeArticle() {
+ this.article = { text: 'Vue 3 is awesome' }
+ },
+ clearComments() {
+ this.comments = []
+ }
+ }
+ })
+ ```
+
+ `$watch` returns an unwatch function that stops firing the callback:
+
+ ```js
+ const app = Vue.createApp({
+ data() {
+ return {
+ a: 1
+ }
+ }
+ })
+
+ const vm = app.mount('#app')
+
+ const unwatch = vm.$watch('a', cb)
+ // later, teardown the watcher
+ unwatch()
+ ```
+
+- **Option: deep**
+
+ To also detect nested value changes inside Objects, you need to pass in `deep: true` in the options argument. Note that you don't need to do so to listen for Array mutations.
+
+ ```js
+ vm.$watch('someObject', callback, {
+ deep: true
+ })
+ vm.someObject.nestedValue = 123
+ // callback is fired
+ ```
+
+- **Option: immediate**
+
+ Passing in `immediate: true` in the option will trigger the callback immediately with the current value of the expression:
+
+ ```js
+ vm.$watch('a', callback, {
+ immediate: true
+ })
+ // `callback` is fired immediately with current value of `a`
+ ```
+
+ Note that with `immediate` option you won't be able to unwatch the given property on the first callback call.
+
+ ```js
+ // This will cause an error
+ const unwatch = vm.$watch(
+ 'value',
+ function() {
+ doSomething()
+ unwatch()
+ },
+ { immediate: true }
+ )
+ ```
+
+ If you still want to call an unwatch function inside the callback, you should check its availability first:
+
+ ```js
+ const unwatch = vm.$watch(
+ 'value',
+ function() {
+ doSomething()
+ if (unwatch) {
+ unwatch()
+ }
+ },
+ { immediate: true }
+ )
+ ```
+
+- **See also:** [Watchers](../guide/computed.html#watchers)
+
+## $emit
+
+- **Arguments:**
+
+ - `{string} eventName`
+ - `[...args]`
+
+ Trigger an event on the current instance. Any additional arguments will be passed into the listener's callback function.
+
+- **Examples:**
+
+ Using `$emit` with only an event name:
+
+ ```html
+
+ `
+ })
+ ```
+
+- **See also:**
+ - [`emits` option](./options-data.html#emits)
+ - [Emitting a Value With an Event](../guide/component-basics.html#emitting-a-value-with-an-event)
+
+## $forceUpdate
+
+- **Usage:**
+
+ Force the Vue instance to re-render. Note it does not affect all child components, only the instance itself and child components with inserted slot content.
+
+## $nextTick
+
+- **Arguments:**
+
+ - `{Function} [callback]`
+
+- **Usage:**
+
+ Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `Vue.nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method.
+
+- **Example:**
+
+ ```js
+ Vue.createApp({
+ // ...
+ methods: {
+ // ...
+ example() {
+ // modify data
+ this.message = 'changed'
+ // DOM is not updated yet
+ this.$nextTick(function() {
+ // DOM is now updated
+ // `this` is bound to the current instance
+ this.doSomethingElse()
+ })
+ }
+ }
+ })
+ ```
+
+- **See also:** [Vue.nextTick](TODO)
diff --git a/src/api/options-lifecycle-hooks.md b/src/api/options-lifecycle-hooks.md
index 11a2bf0242..1603886de8 100644
--- a/src/api/options-lifecycle-hooks.md
+++ b/src/api/options-lifecycle-hooks.md
@@ -44,7 +44,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc
Called after the instance has been mounted, where element, passed to `Vue.createApp({}).mount()` is replaced by the newly created `vm.$el`. If the root instance is mounted to an in-document element, `vm.$el` will also be in-document when `mounted` is called.
- Note that `mounted` does **not** guarantee that all child components have also been mounted. If you want to wait until the entire view has been rendered, you can use [vm.\$nextTick](TODO) inside of `mounted`:
+ Note that `mounted` does **not** guarantee that all child components have also been mounted. If you want to wait until the entire view has been rendered, you can use [vm.$nextTick](../api/instance-methods.html#nexttick) inside of `mounted`:
```js
mounted() {
@@ -81,7 +81,7 @@ All lifecycle hooks automatically have their `this` context bound to the instanc
The component's DOM will have been updated when this hook is called, so you can perform DOM-dependent operations here. However, in most cases you should avoid changing state inside the hook. To react to state changes, it's usually better to use a [computed property](./options-data.html#computed) or [watcher](./options-data.html#watch) instead.
- Note that `updated` does **not** guarantee that all child components have also been re-rendered. If you want to wait until the entire view has been re-rendered, you can use [vm.\$nextTick](TODO) inside of `updated`:
+ Note that `updated` does **not** guarantee that all child components have also been re-rendered. If you want to wait until the entire view has been re-rendered, you can use [vm.$nextTick](../api/instance-methods.html#nexttick) inside of `updated`:
```js
updated() {
diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md
index 8d89faddb2..e013f1e5e7 100644
--- a/src/guide/component-basics.md
+++ b/src/guide/component-basics.md
@@ -226,7 +226,7 @@ When we click on the button, we need to communicate to the parent that it should
```
-Then the child component can emit an event on itself by calling the built-in [**`$emit`** method](TODO:../api/#vm-emit), passing the name of the event:
+Then the child component can emit an event on itself by calling the built-in [**`$emit`** method](../api/instance-methods.html#emit), passing the name of the event:
```html