From 36d039b4c029b2491bc5940ea13192b672deddfd Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <logaretm1@gmail.com>
Date: Thu, 26 Sep 2019 03:23:11 +0200
Subject: [PATCH] docs: added note on 'refs' availability closes #2361

---
 docs/guide/validation-observer.md | 49 +++++++++++++++----------------
 docs/guide/validation-provider.md |  5 ++++
 2 files changed, 29 insertions(+), 25 deletions(-)

diff --git a/docs/guide/validation-observer.md b/docs/guide/validation-observer.md
index 7589be9fa..50b2aa08d 100644
--- a/docs/guide/validation-observer.md
+++ b/docs/guide/validation-observer.md
@@ -22,19 +22,19 @@ Here is a small example, with our refactored components:
 
 The scoped slot is passed an object containing a flags object representing the merged state of all providers registered under the observer. It contains the following properties:
 
-| Name      |                          Type                           | Description                                                                                                                                                                          |
-| :-------- | :-----------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| dirty     |                        `boolean`                        | True if at least one field is dirty.                                                                                                                                                 |
-| pristine  |                        `boolean`                        | True if all fields are pristine (not dirty).                                                                                                                                         |
-| valid     |                        `boolean`                        | True if all fields are valid.                                                                                                                                                        |
-| invalid   |                        `boolean`                        | True if at least one field is invalid.                                                                                                                                               |
-| pending   |                        `boolean`                        | True if at least one field's validation is in progress.                                                                                                                              |
-| touched   |                        `boolean`                        | True if at least one field has been touched (blurred).                                                                                                                               |
-| untouched |                        `boolean`                        | True if all fields haven't been touched (blurred).                                                                                                                                   |
-| errors    |               `{ [x: string]: string[] }`               | An object containing reference to each field errors, each field is keyed by its `vid` prop.                                                                                          |
+| Name      |                          Type                           | Description                                                                                                                                                               |
+| :-------- | :-----------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| dirty     |                        `boolean`                        | True if at least one field is dirty.                                                                                                                                      |
+| pristine  |                        `boolean`                        | True if all fields are pristine (not dirty).                                                                                                                              |
+| valid     |                        `boolean`                        | True if all fields are valid.                                                                                                                                             |
+| invalid   |                        `boolean`                        | True if at least one field is invalid.                                                                                                                                    |
+| pending   |                        `boolean`                        | True if at least one field's validation is in progress.                                                                                                                   |
+| touched   |                        `boolean`                        | True if at least one field has been touched (blurred).                                                                                                                    |
+| untouched |                        `boolean`                        | True if all fields haven't been touched (blurred).                                                                                                                        |
+| errors    |               `{ [x: string]: string[] }`               | An object containing reference to each field errors, each field is keyed by its `vid` prop.                                                                               |
 | validate  | `({ silent: boolean }) => { then: () => Promise<any> }` | A method that triggers validation for all providers. Can be chained using `then` to run a method after validation. Mutates child providers state unless `silent` is true. |
-| passes | `(cb: Function) => Promise<void>` | Calls validation like `validate` and mutates provider's state, accepts a callback to be run only if the validation is successful |
-| reset     |                      `() => void`                       | A method that resets validation state for all providers.                                                                                                                             |
+| passes    |            `(cb: Function) => Promise<void>`            | Calls validation like `validate` and mutates provider's state, accepts a callback to be run only if the validation is successful                                          |
+| reset     |                      `() => void`                       | A method that resets validation state for all providers.                                                                                                                  |
 
 ## Rendering
 
@@ -101,7 +101,7 @@ Validating before submit is very easy way, using the [public methods](#methods)
 <script>
 export default {
   methods: {
-    async submit () {
+    async submit() {
       const isValid = await this.$refs.observer.validate();
       if (!isValid) {
         // ABORT!!
@@ -114,6 +114,10 @@ export default {
 </script>
 ```
 
+:::tip \$refs
+Note that `$refs` are not available until the first render, so make sure to add proper checks for that.
+:::
+
 You can trigger validation from the template using `passes` method which is convenient for running a handler if the form is valid:
 
 ```vue{2}
@@ -190,12 +194,7 @@ Like the `validate` method, we could also reset our form after submitting the va
 
 ```vue{3,34,35,36}
 <template>
-  <ValidationObserver
-    ref="observer"
-    tag="form"
-    @submit.prevent="submit()"
-    v-slot="{ invalid }"
-  >
+  <ValidationObserver ref="observer" tag="form" @submit.prevent="submit()" v-slot="{ invalid }">
     <TextFieldWithValidation rules="required" v-model="first" />
 
     <TextFieldWithValidation rules="required" v-model="second" />
@@ -315,12 +314,12 @@ Below is the reference of the ValidationObserver public API.
 
 ### Props
 
-| Prop | Type      | Default Value | Description                                                                                            |
-| ---- | --------- | ------------- | ------------------------------------------------------------------------------------------------------ |
-| tag  | `string`  | `span`        | The default tag to [render](#rendering).                                                               |
-| slim | `boolean` | `false`       | If true, it will make the observer [renderless](#renderless), only rendering the HTML inside its slot. |
-| disabled | `boolean` | `false`       | If true, the observer will be ignored when `validate` is called by a parent observer. |
-| vid | `string` | random string | if provided it will be used as the observer's id when being registered as a child of a parent observer. |
+| Prop     | Type      | Default Value | Description                                                                                             |
+| -------- | --------- | ------------- | ------------------------------------------------------------------------------------------------------- |
+| tag      | `string`  | `span`        | The default tag to [render](#rendering).                                                                |
+| slim     | `boolean` | `false`       | If true, it will make the observer [renderless](#renderless), only rendering the HTML inside its slot.  |
+| disabled | `boolean` | `false`       | If true, the observer will be ignored when `validate` is called by a parent observer.                   |
+| vid      | `string`  | random string | if provided it will be used as the observer's id when being registered as a child of a parent observer. |
 
 ### Methods
 
diff --git a/docs/guide/validation-provider.md b/docs/guide/validation-provider.md
index 22c08fcb0..25b348a01 100644
--- a/docs/guide/validation-provider.md
+++ b/docs/guide/validation-provider.md
@@ -254,6 +254,11 @@ export default {
 </script>
 ```
 
+:::tip $refs
+Note that `$refs` are not available until the first render, so make sure to add proper checks for that.
+:::
+
+
 If you only plan to trigger manual validation using the UI, you can use the `validate` handler on the v-slot data to trigger validation without having to use `refs`.
 
 ```vue{3,6}