v2 blog post

pages/blog/swr-v2.en-US.mdx

@@ -27,35 +27,19 @@ SWR now uses `useSyncExternalStore` and `startTransition` internally to improve
 
 `isLoading` is a new return value that indicates if there's an ongoing request and no "loaded data". Previously, you have to check `data` and `error` are `undefined`, but now you can use the `isLoading` value.
 
-You can improve the user experience by combining with `isLoading` and `isValidating` like this.
-
 ```jsx
-function Stock() {
-  const { data, isLoading, isValidating } = useSWR(STOCK_API, fetcher, {
-    refreshInterval: 3000
-  });
+import useSWR from 'swr'
 
-  // If it's still loading the initial data, there is nothing to display.
-  // We return a skeleton here.
-  if (isLoading) return <div className="skeleton" />;
+function Profile() {
+  const { data, isLoading } = useSWR('/api/user', fetcher)
 
-  // Otherwise, display the data and a spinner that indicates a background
-  // revalidation.
-  return (
-    <>
-      <div>AAPL ${data}</div>
-      {isValidating ? <div className="spinner" /> : null}
-    </>
-  );
+  if (isLoading) return <div>loading...</div>
+  return <div>hello {data.name}!</div>
 }
 ```
 
-![An example using the isLoading state](https://user-images.githubusercontent.com/3676859/163695538-9ed6232d-808c-4c83-8606-0dd22bce508d.gif)
-
-You can find the full code for this example here: https://codesandbox.io/s/swr-isloading-v8dfpy.
-
 <Callout emoji="📝">
-  We have added the new [Understanding SWR](/docs/advanced/understanding) page to describe how SWR returns values.
+  We have added the new [Understanding SWR](/docs/advanced/understanding) page to describe how SWR returns values, which includes the difference between `isValidating` and `isLoading`, and how to combine them to improve user exeprience.
 </Callout>
 
 

pages/docs/advanced/understanding.en-US.mdx

@@ -1,3 +1,4 @@
+import Callout from 'nextra-theme-docs/callout'
 import Video from 'components/video'
 
 # Understanding SWR
@@ -42,6 +43,42 @@ This pattern is to fetch data and change the key and revalidate it later with th
 
 ![A pattern for key change + previous data + fallback](/img/understanding/key-change-previous-data-fallback.svg)
 
+## Combining with isLoading and isValidating for better UX
+
+`isLoading` and `isValidating` are similar, so you might be confused about which value you should use.
+`isValidating` becomes `true` whenever there is an ongoing request, on the other hand, `isLoading` becomes `true` when there is an ongoing request and no "loaded data".
+
+You can use `isValidating` for indicating there is an ongoing revalidation and `isLoading` for indicating there is nothing to display.
+
+<Callout emoji="📝">
+  Fallback data and previous data are not considered "loaded data," so when you use fallback data or enable the keepPreviousData option, you might have data to display.
+</Callout>
+
+```jsx
+function Stock() {
+  const { data, isLoading, isValidating } = useSWR(STOCK_API, fetcher, {
+    refreshInterval: 3000
+  });
+
+  // If it's still loading the initial data, there is nothing to display.
+  // We return a skeleton here.
+  if (isLoading) return <div className="skeleton" />;
+
+  // Otherwise, display the data and a spinner that indicates a background
+  // revalidation.
+  return (
+    <>
+      <div>${data}</div>
+      {isValidating ? <div className="spinner" /> : null}
+    </>
+  );
+}
+```
+
+![An example using the isLoading state](/img/understanding/isloading.gif)
+
+You can find the full code for this example here: https://codesandbox.io/s/swr-isloading-jtopow
+
 ## Return previous data for better UX
 
 When doing data fetching based on continuous user actions, e.g. real-time search when typing, keeping the previous fetched data can improve the UX a lot. `keepPreviousData` is an option to enable that behavior. Here's a simple search UI: