feat(native): add first-time user onboarding on home screen (#690)

Author: aneepal55

apps/native/app/(tabs)/_layout.tsx

@@ -1,25 +1,28 @@
 import { Tabs } from "expo-router";
 import CustomTabBar from "@/components/CustomTabBar";
+import { CopilotProvider } from "react-native-copilot";
 
 export default function TabLayout() {
   return (
-    <Tabs
-      // @ts-ignore
-      tabBar={(props) => <CustomTabBar {...props} />}
-      screenOptions={{
-        headerShown: false,
-      }}
-    >
-      <Tabs.Screen name="home" />
-      <Tabs.Screen name="wallet" />
-      <Tabs.Screen name="notifications" />
-      <Tabs.Screen name="settings" />
-      <Tabs.Screen
-        name="search"
-        options={{
-          href: null,
+    <CopilotProvider>
+      <Tabs
+        // @ts-ignore
+        tabBar={(props) => <CustomTabBar {...props} />}
+        screenOptions={{
+          headerShown: false,
         }}
-      />
-    </Tabs>
+      >
+        <Tabs.Screen name="home" />
+        <Tabs.Screen name="wallet" />
+        <Tabs.Screen name="notifications" />
+        <Tabs.Screen name="settings" />
+        <Tabs.Screen
+          name="search"
+          options={{
+            href: null,
+          }}
+        />
+      </Tabs>
+    </CopilotProvider>
   );
 }

apps/native/app/(tabs)/home/index.tsx

@@ -1,9 +1,10 @@
-import React, { useEffect } from "react";
+import React, { useEffect, useRef } from "react";
 import { useAtom } from "jotai";
 import { StyleSheet, Text, View, TouchableOpacity } from "react-native";
 import { FlashList } from "@shopify/flash-list";
 import { useRouter } from "expo-router";
 import { MaterialCommunityIcons, MaterialIcons } from "@expo/vector-icons";
+import { CopilotStep, walkthroughable, useCopilot } from "react-native-copilot";
 import Heading from "@common/Heading";
 import WalletSummary from "@components/ui/WalletSummary";
 import { THEME, TypographyWeight } from "@/theme";
@@ -23,10 +24,14 @@ export const balanceData = [
   { id: 2, value: "2", label: "Wallets", icon: "wallet-outline" },
 ];
 
+const WalkthroughableView = walkthroughable(View);
+
 export default function Home() {
   const [isSearching] = useAtom(isSearchingAtom);
   const [isLoading] = useAtom(searchLoadingAtom);
   const [, selectCategory] = useAtom(selectCategoryAtom);
+  const { start } = useCopilot();
+  const hasStartedRef = useRef(false);
 
   const router = useRouter();
 
@@ -41,6 +46,19 @@ export default function Home() {
     }
   }, [selectCategory, isSearching]);
 
+  useEffect(() => {
+    if (isSearching || isLoading || hasStartedRef.current) {
+      return;
+    }
+
+    const timeout = setTimeout(() => {
+      hasStartedRef.current = true;
+      start();
+    }, 300);
+
+    return () => clearTimeout(timeout);
+  }, [isLoading, isSearching, start]);
+
   const ActivityHeader = () => (
     <View
       style={{
@@ -50,25 +68,10 @@ export default function Home() {
     >
       <View style={[styles.balancesContainer, { gap: spacing.md }]}>
         {balanceData.map((item) => (
-          <WalletSummary
+          <BalanceCard
             key={item.id}
-            value={item.value}
-            icon={
-              item.label === "Tokens" ? (
-                <MaterialIcons name="toll" size={24} color={colors.primary} />
-              ) : (
-                <MaterialCommunityIcons
-                  name="wallet-outline"
-                  size={24}
-                  color={colors.gray700}
-                />
-              )
-            }
-            label={item.label}
-            style={[
-              styles.balanceCard,
-              { width: Math.max(layout.screenPadding * 8, 140) },
-            ]}
+            item={item}
+            cardWidth={Math.max(layout.screenPadding * 8, 140)}
           />
         ))}
       </View>
@@ -150,6 +153,65 @@ export default function Home() {
   );
 }
 
+function BalanceCard({
+  item,
+  cardWidth,
+}: {
+  item: (typeof balanceData)[number];
+  cardWidth: number;
+}) {
+  const { colors } = THEME;
+
+  const content = (
+    <WalletSummary
+      value={item.value}
+      icon={
+        item.label === "Tokens" ? (
+          <MaterialIcons name="toll" size={24} color={colors.primary} />
+        ) : (
+          <MaterialCommunityIcons
+            name="wallet-outline"
+            size={24}
+            color={colors.gray700}
+          />
+        )
+      }
+      label={item.label}
+      style={[styles.balanceCard, { width: cardWidth }]}
+    />
+  );
+
+  if (item.label === "Tokens") {
+    return (
+      <CopilotStep
+        text={
+          "Here you can view the total amount of tokens (a digital asset representing your contributions)."
+        }
+        order={1}
+        name="homeTokens"
+      >
+        <WalkthroughableView>{content}</WalkthroughableView>
+      </CopilotStep>
+    );
+  }
+
+  if (item.label === "Wallets") {
+    return (
+      <CopilotStep
+        text={
+          "Here you can see the total amount of wallets (restricted to max 2 at this time)."
+        }
+        order={2}
+        name="homeWallets"
+      >
+        <WalkthroughableView>{content}</WalkthroughableView>
+      </CopilotStep>
+    );
+  }
+
+  return content;
+}
+
 const styles = StyleSheet.create({
   container: {
     flex: 1,

apps/native/components/CustomTabBar.tsx

@@ -3,6 +3,9 @@ import { View, Text, Pressable, StyleSheet, Platform } from "react-native";
 import { BottomTabBarProps } from "@react-navigation/bottom-tabs";
 import { MaterialIcons } from "@expo/vector-icons";
 import { ModalContext } from "@/context/ModalContext";
+import { CopilotStep, walkthroughable } from "react-native-copilot";
+
+const WalkthroughableView = walkthroughable(View);
 
 export default function CustomTabBar({
   state,
@@ -23,19 +26,25 @@ export default function CustomTabBar({
         if (index === midpoint) {
           return (
             <React.Fragment key="chooseAction">
-              <Pressable
-                onPress={handleChooseActionPress}
-                style={styles.sendButtonWrapper}
-                android_ripple={{
-                  color: "#dcdcdc",
-                  radius: 40,
-                  borderless: true,
-                }}
+              <CopilotStep
+                text={"Tap to send or request tokens."}
+                order={3}
+                name="homeSendAction"
               >
-                <View style={styles.sendButton}>
-                  <MaterialIcons name="swap-horiz" size={26} color="#fff" />
-                </View>
-              </Pressable>
+                <WalkthroughableView style={styles.sendButtonWrapper}>
+                  <Pressable
+                    onPress={handleChooseActionPress}
+                    style={styles.sendButton}
+                    android_ripple={{
+                      color: "#dcdcdc",
+                      radius: 40,
+                      borderless: true,
+                    }}
+                  >
+                    <MaterialIcons name="swap-horiz" size={26} color="#fff" />
+                  </Pressable>
+                </WalkthroughableView>
+              </CopilotStep>
               {renderTab(route, index)}
             </React.Fragment>
           );

apps/native/package.json

@@ -64,6 +64,7 @@
     "react-compiler-runtime": "^19.1.0-rc.2",
     "react-dom": "19.1.0",
     "react-native": "0.81.5",
+    "react-native-copilot": "^3.3.3",
     "react-native-gesture-handler": "~2.28.0",
     "react-native-paper": "^5.12.3",
     "react-native-reanimated": "~4.1.1",