Add native table of contents navigation for multi-page content products by yashranaway · Pull Request #70 · antiwork/gumroad-mobile

yashranaway · 2026-02-21T06:58:43Z

Issue: #27

Description

Problem

Products with multiple content pages show a web-based TOC button and Previous/Next buttons at the bottom of the HTML content in the WebView. This requires scrolling down on long pages to navigate between pages, which is a poor mobile UX.

Solution

Replace the web-based navigation with a native sticky footer bar that is always visible. The footer has Previous/Next buttons, a page counter ("2 of 5"), and a TOC button that opens a sheet with the full page list.

Mobile app changes (gumroad-mobile):

New ContentPageNav component: sticky footer with Previous/Next, page counter, and TOC sheet
Updated purchase page to handle tocData messages from web and send mobileAppPageChange messages back

Web changes (gumroad):

Hide web TOC/Previous/Next nav when in mobile app WebView
Send tocData message to React Native with pages and active index
Listen for mobileAppPageChange messages from React Native

Companion web changes: This feature requires changes to gumroad web repo (WithContent.tsx). The implementation is ready on branch feat/native-toc-navigation but I'm unable to open a PR on antiwork/gumroad since it's limited to collaborators. The web-side diff is small (1 file, ~40 lines) happy to share it however is preferred.

Before/After

before

after

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2026-02-21.at.12.07.02.mov

Test Results

Checklist

I have read the contributing guidelines
I have watched Gumroad PR review livestreams
I have performed a self-review and left review comments on my PR
I have added/updated tests for my changes

AI Disclosure

Claude Opus 4.6 was used to assist with implementation and test writing.

Replace the web-based TOC/Previous/Next buttons (which required scrolling down) with a native sticky footer bar that shows page navigation and a TOC sheet.

yashranaway

@binary-koan _a Could you please take a look?

yashranaway · 2026-02-21T07:03:13Z

+type TocPage = {
+  page_id: string;
+  title: string | null;
+};


Kept this as a local type rather than importing from the purchase page since this component doesn't need to know about the message protocol — it just needs page IDs and titles.

yashranaway · 2026-02-21T07:03:27Z

+        <Pressable
+          onPress={() => onPageChange(activePageIndex - 1)}
+          disabled={!hasPrevious}
+          className={cn("flex-row items-center gap-1", !hasPrevious && "opacity-50")}


Following the codebase pattern from Button, Checkbox, RadioGroup etc. where disabled Pressables get opacity-50 rather than changing individual child colors.

yashranaway · 2026-02-21T07:07:20Z

+        <Pressable onPress={() => setSheetOpen(true)} className="flex-1 flex-row items-center justify-center gap-1.5">
+          <LineIcon name="book-content" size={18} className="text-foreground" />
+          <Text className="text-sm font-bold text-foreground">
+            {activePageIndex + 1} of {pages.length}
+          </Text>
+        </Pressable>


The center area is flex-1 so it fills the space between Previous and Next, keeping the layout balanced. Tapping opens the sheet — I used book-content icon since it felt fitting for a table of contents.

yashranaway · 2026-02-21T07:07:41Z

+      <Sheet open={sheetOpen} onOpenChange={setSheetOpen}>
+        <SheetHeader onClose={() => setSheetOpen(false)}>
+          <SheetTitle>Table of contents</SheetTitle>
+        </SheetHeader>
+        <SheetContent>
+          <FlatList
+            data={pages}
+            keyExtractor={(item) => item.page_id}
+            renderItem={({ item, index }) => {
+              const isActive = index === activePageIndex;
+              return (
+                <Pressable
+                  onPress={() => {
+                    onPageChange(index);
+                    setSheetOpen(false);
+                  }}
+                  className={cn("flex-row items-center gap-3 px-4 py-3", isActive && "bg-accent")}
+                >
+                  <Text className={cn("text-sm", isActive ? "font-bold text-accent-foreground" : "text-foreground")}>
+                    {index + 1}.
+                  </Text>
+                  <Text
+                    className={cn(
+                      "flex-1 text-sm",
+                      isActive ? "font-bold text-accent-foreground" : "text-foreground",
+                    )}
+                    numberOfLines={2}
+                  >
+                    {item.title ?? "Untitled"}
+                  </Text>
+                </Pressable>
+              );
+            }}
+          />
+        </SheetContent>
+      </Sheet>


Using FlatList inside SheetContent so the list scrolls independently if there are many pages. Active page gets bg-accent highlight to match the brand pink. Sheet closes after selecting a page so the user sees the content change immediately.

yashranaway · 2026-02-21T07:07:59Z

+        <SheetContent>
+          <FlatList
+            data={pages}
+            keyExtractor={(item) => item.page_id}


Using page_id from the web data as the key, which is guaranteed unique per product.

yashranaway · 2026-02-21T07:08:15Z

+type TocDataMessage = {
+  type: "tocData";
+  payload: {
+    pages: { page_id: string; title: string | null }[];
+    activePageIndex: number;
+  };
+};
+


Mirrors the exact shape sent by the web side's useEffect in WithContent.tsx. The pages array is a slimmed-down version of RichContentPage — we only need page_id and title for the native nav.

yashranaway · 2026-02-21T07:08:39Z

 export default function DownloadScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  const [isDownloading, setIsDownloading] = useState(false);
+  const [tocPages, setTocPages] = useState<TocDataMessage["payload"]["pages"]>([]);


Reusing the type from the message definition to keep them in sync. Starts empty so the footer doesn't render until the web sends data.

yashranaway · 2026-02-21T07:09:05Z

+  const handleNativePageChange = useCallback(
+    (pageIndex: number) => {
+      webViewRef.current?.postMessage(JSON.stringify({ type: "mobileAppPageChange", payload: { pageIndex } }));
+    },
+    [],
+  );
+


Wrapped in useCallback since it's passed as a prop to ContentPageNav. This sends a message to the WebView which then does the actual page change (calling handlePageChange on the web side, which updates state AND calls saveLastContentPage). The web then round-trips back with updated tocData, so the native side stays in sync without duplicating page-change logic.

yashranaway · 2026-02-21T07:09:22Z

    const data = event.nativeEvent.data;
    try {
-      const message = JSON.parse(data) as ClickMessage;
+      const message = JSON.parse(data) as ClickMessage | TocDataMessage;


Changed from as ClickMessage to as ClickMessage | TocDataMessage so we can handle both message types. The if (message.type === "tocData") check runs first, before the existing click handling.

yashranaway · 2026-02-21T07:09:51Z

+      if (message.type === "tocData") {
+        setTocPages(message.payload.pages);
+        setActivePageIndex(message.payload.activePageIndex);
+        return;
+      }
+


Just stores the page list and active index. The web side is the single source of truth b.

binary-koan · 2026-02-27T02:49:24Z

Looking at the diff on web, I think we should factor out a common hook for dealing with React Native messages - all the window vs document stuff, JSON parsing, etc shouldn't be duplicated

We also unfortunately need to detect the Expo app specifically rather than any mobile app, since I believe just checking props.is_mobile_app_web_view will hide it on the current native apps which still need it

I'll think about the design a bit as well, the ToC button doesn't obviously look clickable to me so I wonder if we can make it clearer (I'll think about what apps we can compare to, lmk if you have any good examples!)

yashranaway · 2026-02-27T03:09:12Z

@binary-koan _a Thanks I have made these changes,

For the shared hook I extracted a useReactNativeMessage hook that handles the window vs document listener, JSON parsing, and type checking. Both WithContent.tsx and FileList.tsx use it now.
For Expo detection, didn't think about the existing native apps still needing the web TOC. Changed the Expo app to send display=expo_app instead of mobile_app. On the Rails side, is_mobile_app_web_view stays true for both (so Layout hiding etc. still works for all native apps), and a new is_expo_app flag gates just the TOC stuff (hiding the web nav + sending tocData messages).

Now for the design totally fair, the center button is pretty subtle. Looked at a few apps for reference: Apple Books has a similar bottom bar with arrows and a centered TOC button, Kindle does a thin bar that opens a page scrubber + TOC, Substack Reader uses a floating pill with the chapter title. Ours is closest to Apple Books. Could make it more obviously tappable by adding a border/pill around the center, adding a chevron-down next to "1 of 5", or swapping the icon for something more universally "list-like". Happy to try whatever direction you land on!

binary-koan · 2026-02-28T00:39:10Z

Works great locally, had a go at updating the design. The Previous/Next buttons being different widths and making the middle button slightly off center was bugging me so I tried changing the order, and also generally updated the design to be closer to what we have on web.

Simulator Screenshot - iPhone 16 Pro - 2026-02-27 at 23 46 56

Simulator Screenshot - iPhone 16 Pro - 2026-02-28 at 00 38 06

Will do a final check and merge tomorrow

yashranaway · 2026-02-28T04:28:28Z

Looks great! Thanks.

Paired with antiwork/gumroad-mobile#70 * Adds support for sending the table of contents to the Expo app and navigating when requested * Hides the web navigation when running in React Native --------- Co-authored-by: Aditya Garud <[email protected]> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Add native table of contents navigation for multi-page content products

4bfbadf

Replace the web-based TOC/Previous/Next buttons (which required scrolling down) with a native sticky footer bar that shows page navigation and a TOC sheet.

yashranaway commented Feb 21, 2026

View reviewed changes

yashranaway marked this pull request as ready for review February 21, 2026 07:10

binary-koan assigned binary-koan and yashranaway Feb 27, 2026

binary-koan mentioned this pull request Feb 27, 2026

Render table of contents natively on the purchase page #74

Closed

Use expo_app display param for Expo-specific detection

6652b32

binary-koan mentioned this pull request Feb 27, 2026

Support native table of contents in Expo app antiwork/gumroad#3844

Merged

binary-koan added 3 commits February 27, 2026 23:04

Fix

f4f146a

Merge branch 'main' into feat/native-toc-navigation

5c18c8f

UI improvements

cbec69f

binary-koan mentioned this pull request Feb 28, 2026

Render table of contents natively on the purchase page #83

Closed

4 tasks done

binary-koan merged commit 0719345 into antiwork:main Feb 28, 2026
2 checks passed

yashranaway deleted the feat/native-toc-navigation branch February 28, 2026 16:26

pegasus1134 mentioned this pull request Feb 28, 2026

feat: Paginate library with server-side filtering (#23) #69

Merged

4 tasks done

Conversation

yashranaway commented Feb 21, 2026

Description

Problem

Solution

Before/After

before

after

Test Results

Checklist

AI Disclosure

Uh oh!

yashranaway left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

binary-koan commented Feb 27, 2026

Uh oh!

yashranaway commented Feb 27, 2026

Uh oh!

binary-koan commented Feb 28, 2026

Uh oh!

yashranaway commented Feb 28, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants