From 23d46c8e1a4e5d28dcf671bef895502895a1ff8e Mon Sep 17 00:00:00 2001
From: fzaninotto <fzaninotto@gmail.com>
Date: Wed, 23 Jun 2021 15:19:13 +0200
Subject: [PATCH] [Doc] Fix misleading explanation of <List syncWithLocation>
 prop

---
 docs/List.md | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/docs/List.md b/docs/List.md
index 18273c3d154..57c59d5a57d 100644
--- a/docs/List.md
+++ b/docs/List.md
@@ -787,25 +787,27 @@ The default value for the `component` prop is `Card`.
 
 ### Synchronize With URL
 
-When a List based component (eg: `PostList`) is passed to the `list` prop of a `<Resource>`, it will automatically synchronize its parameters with the browser URL (using react-router location). However, when used anywhere outside a `<Resource>`, it won't synchronize, which can be useful when you have multiple lists on a single page for example.
+When a `<List>` based component (eg: `<PostList>`) is passed as a `<Resource list>`, react-admin synchronizes its parameters (sort, pagination, filters) with the query string in the URL (using `react-router` location). It does so by setting the `<List syncWithLocation>` prop by default.
 
-In order to enable the synchronization with the URL, you can set the `syncWithLocation` prop. For example, adding a `List` to an `Edit` page:
+When you use a `<List>` component anywhere else than as `<Resource list>`, `syncWithLocation` isn't enabled, and so `<List>` doesn't synchronize its parameters with the URL - the `<List>` parameters are kept in a local state, independent for each `<List>` instance. This allows to have multiple lists on a single page. The drawback is that a hit on the "back" button doesn't restore the previous list parameters.
+
+You may, however, wish to enable `syncWithLocation` on a `<List>` component that is not a `<Resource list>`. For instance, you may want to display a `<List>` of Posts in a Dashboard, and allow users to use the "back" button to undo a sort, pagination, or filter change on that list. In such cases, set the `syncWithLocation` prop to `true`:
 
 {% raw %}
 ```jsx
-const TagsEdit = (props) => (
-    <>
-        <Edit {...props}>
-            // ...
-        </Edit>
+const Dashboard = () => (
+    <div>
+        // ...
         <ResourceContextProvider value="posts">
-            <List syncWithLocation basePath="/posts" filter={{ tags: [id]}}>
-                <Datagrid>
-                    <TextField source="title" />
-                </Datagrid>
+            <List syncWithLocation basePath="/posts" >
+                <SimpleList
+                    primaryText={record => record.title}
+                    secondaryText={record => `${record.views} views`}
+                    tertiaryText={record => new Date(record.published_at).toLocaleDateString()}
+                />
             </List>
         </ResourceContextProvider>
-    </>
+    </div>
 )
 ```
 {% endraw %}