From e3e61916b3e5cb5312afd5d045a16322a599e4da Mon Sep 17 00:00:00 2001
From: Will Chen <willchen90@gmail.com>
Date: Tue, 6 Feb 2024 11:38:50 -0800
Subject: [PATCH] Create example & update docs for multi-page navigation

---
 docs/guides/pages.md                  | 18 ++++++++++++++++--
 mesop/examples/docs/__init__.py       |  1 +
 mesop/examples/docs/multi_page_nav.py | 23 +++++++++++++++++++++++
 3 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 mesop/examples/docs/multi_page_nav.py

diff --git a/docs/guides/pages.md b/docs/guides/pages.md
index 51e920a12..c4fa68541 100644
--- a/docs/guides/pages.md
+++ b/docs/guides/pages.md
@@ -4,7 +4,7 @@ You can define multi-page Mesop applications by using the page feature you learn
 
 ## Simple, 1-page setup
 
-If you want to create a simple Mesop app, you can do the following:
+To create a simple Mesop app, you can use `me.page()` like this:
 
 ```python
 import mesop as me
@@ -14,10 +14,12 @@ def foo():
     me.text("bar")
 ```
 
-This is the same as the following example which more explicitly sets the route to `"/"`.
+> NOTE: If you do not provide a `path` argument, then it defaults to the root path `"/"`.
 
 ## Explicit 1-page setup
 
+This is the same as the above example which explicitly sets the route to `"/"`.
+
 ```python
 import mesop as me
 
@@ -39,3 +41,15 @@ def page1():
 def page2():
     me.text("page 2")
 ```
+
+## Navigation
+
+If you have multiple pages, you will typically want to navigate from one page to another when the user clicks a button. You can use `me.navigate("/to/path")` to navigate to another page.
+
+**Example:**
+
+```python
+--8<-- "mesop/examples/docs/multi_page_nav.py"
+```
+
+> Note: you can re-use state across pages. See how the above example uses the `State#count` value across pages.
diff --git a/mesop/examples/docs/__init__.py b/mesop/examples/docs/__init__.py
index 686013d72..530a4a23b 100644
--- a/mesop/examples/docs/__init__.py
+++ b/mesop/examples/docs/__init__.py
@@ -1,4 +1,5 @@
 from mesop.examples.docs import counter as counter
 from mesop.examples.docs import hello_world as hello_world
 from mesop.examples.docs import loading as loading
+from mesop.examples.docs import multi_page_nav as multi_page_nav
 from mesop.examples.docs import streaming as streaming
diff --git a/mesop/examples/docs/multi_page_nav.py b/mesop/examples/docs/multi_page_nav.py
new file mode 100644
index 000000000..09099a391
--- /dev/null
+++ b/mesop/examples/docs/multi_page_nav.py
@@ -0,0 +1,23 @@
+import mesop as me
+
+
+def on_click(e: me.ClickEvent):
+  state = me.state(State)
+  state.count += 1
+  me.navigate("/multi_page_nav/page_2")
+
+
+@me.page(path="/multi_page_nav")
+def main_page():
+  me.button("Navigate to Page 2", on_click=on_click)
+
+
+@me.page(path="/multi_page_nav/page_2")
+def page_2():
+  state = me.state(State)
+  me.text(f"Page 2 - count: {state.count}")
+
+
+@me.stateclass
+class State:
+  count: int