Document changes in #8875

docs/shared/mutation-result.mdx

@@ -120,6 +120,21 @@ The instance of Apollo Client that executed the mutation.
 
 Can be useful for manually executing followup operations or writing data to the cache.
 
+</td>
+</tr>
+
+<tr>
+<td>
+
+###### `reset`
+
+`() => void`
+</td>
+
+<td>
+
+A function that you can call to reset the mutation's result to its initial, uncalled state.
+
 </td>
 </tr>
   </tbody>

docs/source/api/react/hooks.mdx

@@ -149,7 +149,7 @@ function useLazyQuery<TData = any, TVariables = OperationVariables>(
   query: DocumentNode,
   options?: LazyQueryHookOptions<TData, TVariables>,
 ): [
-  (options?: QueryLazyOptions<TVariables>) => void,
+  (options?: QueryLazyOptions<TVariables>) => Promise<LazyQueryResult<TData, TVariables>>,
   LazyQueryResult<TData, TVariables>
 ] {}
 ```
@@ -166,15 +166,15 @@ function useLazyQuery<TData = any, TVariables = OperationVariables>(
 
 <QueryOptions3 />
 
-### Result
+### Result tuple
 
-**Execute function**
+**Execute function (first tuple item)**
 
 | Param            | Type                                                  | Description                                                                                                                     |
 | ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Execute function | (options?: QueryLazyOptions&lt;TVariables&gt;) => void | Function that can be triggered to execute the suspended query. After being called, `useLazyQuery` behaves just like `useQuery`. |
+| Execute function | `(options?: QueryLazyOptions<TVariables>) => Promise<LazyQueryResult<TData, TVariables>>` | Function that can be triggered to execute the suspended query. After being called, `useLazyQuery` behaves just like `useQuery`. The `useLazyQuery` function returns a promise that fulfills with a query result when the query succeeds or fails. |
 
-**Result object**
+**`LazyQueryResult<TData, TVariables>` object (second tuple item)**
 
 <QueryResult3 />
 
@@ -242,7 +242,7 @@ function useMutation<TData = any, TVariables = OperationVariables>(
 
 <MutationOptions3 />
 
-### Result
+### `MutationTuple<TData, TVariables>` result tuple
 
 <MutationResult3 />
 

docs/source/data/mutations.mdx

@@ -151,6 +151,41 @@ if (error) return `Submission error! ${error.message}`;
 
 > The `useMutation` hook also supports `onCompleted` and `onError` options if you prefer to use callbacks. [See the API reference.](../api/react/hooks/#options-2)
 
+### Resetting mutation status
+
+The mutation result object returned by `useMutation` includes a [`reset` function](#reset):
+
+```js
+const [login, { data, loading, error, reset }] = useMutation(LOGIN_MUTATION);
+```
+
+Call `reset` to reset the mutation's result to its initial state (i.e., _before_ the mutate function was called). You can use this to enable users to dismiss mutation result data or errors in the UI.
+
+> Calling `reset` does _not_ remove any cached data returned by the mutation's execution. It only affects the state associated with the `useMutation` hook, causing the corresponding component to rerender.
+
+```js{2,15}
+function LoginPage () {
+  const [login, { error, reset }] = useMutation(LOGIN_MUTATION);
+
+  return (
+    <>
+      <form>
+        <input class="login"/>
+        <input class="password"/>
+        <button onclick={login}>Login</button>
+      </form>
+      {
+        error &&
+        <LoginFailedMessageWindow
+          message={error.message}
+          onDismiss={() => reset()}
+        />
+      }
+    </>
+  );
+}
+```
+
 ## Updating local data
 
 When you execute a mutation, you modify back-end data. Usually, you then want to update your _locally cached_ data to reflect the back-end modification. For example, if you execute a mutation to add an item to your to-do list, you also want that item to appear in your cached copy of the list.