HOOKS

Hooks are special functions that let you “hook into” React features. They allow you to use state and other React capabilities without writing a class component.

✨ useAnimatedText

This hook utilizes React Native Reanimated to add a smooth, professional visual flourish to any dynamic content display. When the underlying value changes (e.g., a score update or a metric change), the text seamlessly fades out, updates, and fades back in with a subtle bounce effect. This eliminates jarring, abrupt updates, enhancing the user experience.

const ScoreDisplay = () => {
  const [score, setScore] = useState(100);
 
  // Hook handles the fade and scale animation when 'score' changes
  const { displayValue, animatedStyle } = useAnimatedText({
    initialValue: score,
  });
 
  return (
    <View>
      {/* Apply the animated style and display the transitional value */}
      <Animated.Text style={[styles.largeText, animatedStyle]}>
        {displayValue}
      </Animated.Text>
 
      <Button title='Increase Score' onPress={() => setScore((s) => s + 5)} />
    </View>
  );
};

⚡ useAsync

This utility hook provides a clean, modern way to manage the state of any Promise-returning function that needs to execute immediately upon component mount. It automatically tracks the three states of the operation: loading, error, and value.

This hook is ideal for simple data fetching scenarios, ensuring you eliminate boilerplate useState and useEffect logic.

const ProfileScreen = ({ userId }) => {
  // Define the function that fetches user data
  const fetchProfile = async () => {
    return api.get(`/users/${userId}`);
  };
 
  // Hook executes immediately on mount/dependency change and manages state
  const state = useAsync(fetchProfile, [userId]);
 
  if (state.loading) {
    return <ActivityIndicator />;
  }
 
  if (state.error) {
    return <Text>Error: {state.error.message}</Text>;
  }
 
  return (
    <View>
      <Text>{state.value.name}</Text>
    </View>
  );
};

This hook (useAuth) is the cornerstone of your entire application’s security and user experience. It’s a critical feature that saves developers massive amounts of time.

Here is the documentation for useAuth, written in the concise, sales-focused markdown style you requested:

🔐 useAuth

The useAuth hook is the single source of truth for user authentication, session status, and user data. It is pre-wired to Supabase to automatically handle login, logout, session persistence, and real-time state changes.

This hook is essential for protecting routes, conditionally rendering UI elements, and providing an instant-loading user experience upon application launch.

const RootLayout = () => {
  // Hook manages all auth status and session persistence
  const { isAuthenticated, isAuthenticating } = useAuth();
 
  if (isAuthenticating) {
    // Show splash screen or loading indicator while checking local session
    return <SplashScreen />;
  }
 
  return (
    <Stack>
      {/* Conditionally render screens based on authentication status */}
      <Stack.Screen
        name={isAuthenticated ? '(app)' : '(auth)'}
        options={{ headerShown: false }}
      />
    </Stack>
  );
};

This is a custom wrapper hook built on top of NativeWind’s color scheme functionality, designed to provide a centralized and streamlined way to manage dark mode and theming in your application.

Following your requested sales-focused, short documentation style:

🎨 useColorScheme

The useColorScheme hook is the centralized utility for accessing and controlling the application’s current theme (light or dark mode). It is a simple, effective wrapper around the NativeWind hook, providing immediate access to the theme status.

This is critical for dynamically adjusting UI elements, images, or logic based on the user’s preferred color scheme.

const ThemeToggle = () => {
  // Hook provides the current status and toggle function
  const { isDarkColorScheme, toggleColorScheme } = useColorScheme();
 
  return (
    <Button
      title={isDarkColorScheme ? 'Switch to Light Mode' : 'Switch to Dark Mode'}
      // Function instantly changes the theme for the entire app
      onPress={toggleColorScheme}
    />
  );
};

This hook (useDebounce) is a fundamental utility for controlling the frequency of state updates and function calls, crucial for performance optimization.

Following your instructions for a sales-focused, short documentation with a minimal sample, no imports, no parameter/output descriptions, and no key outputs section:

⏱️ useDebounce

The useDebounce hook is a performance optimization utility that limits how often a value can change. It prevents expensive operations (like API calls or heavy computations) from running every time a state changes, ensuring they only run after a specified period of inactivity.

This is essential for inputs like search bars, where you only want to search after the user finishes typing.

const SearchComponent = () => {
  const [searchTerm, setSearchTerm] = useState('');
 
  // The debouncedValue only updates 500ms after the user stops typing
  const debouncedSearchTerm = useDebounce(searchTerm, 500);
 
  // useEffect triggers only when debouncedSearchTerm updates
  useEffect(() => {
    if (debouncedSearchTerm) {
      // API call to fetch search results
      fetchResults(debouncedSearchTerm);
    }
  }, [debouncedSearchTerm]);
 
  return (
    <TextInput
      placeholder='Start typing to search...'
      value={searchTerm}
      onChangeText={setSearchTerm}
    />
  );
};

🔔 useNotificationPermissions

This hook is the central utility for managing user consent for push notifications using expo-notifications. It handles checking the current status, defining what “granted” means (including provisional status on iOS), and providing a clean function to trigger the permission request when needed.

This is essential for correctly integrating notification features and ensuring your app respects user preferences on both iOS and Android.

const NotificationToggle = () => {
  // Hook returns the current status and the function to prompt the user
  const { isGranted, requestPermissions } = useNotificationPermissions();
 
  const handlePress = () => {
    if (isGranted === false) {
      // Prompt user to grant permissions
      requestPermissions({
        ios: { scope: ['alert', 'sound', 'badge'] },
      });
    }
    // Logic to navigate to native settings if status is denied
  };
 
  return (
    <View>
      <Text>
        {isGranted ? 'Notifications are ON' : 'Notifications are OFF'}
      </Text>
      <Button
        title={isGranted === false ? 'Enable Notifications' : 'Manage'}
        onPress={handlePress}
      />
    </View>
  );
};

💎 useSubscription

Here is the shortened, punchier version:

The useThemeConfig hook centrally manages your application’s theme by synchronizing React Navigation’s colors (headers, backgrounds) with the current NativeWind (dark/light mode) state. This ensures a seamless, consistent theme across both custom components and the native navigation stack, preventing visual mismatches.

const PaywallScreen = () => {
  // Hook provides state (packages, isSubscribed) and actions (purchaseSubscription)
  const { packages, isSubscribed, purchaseSubscription } = useSubscription();
 
  if (isSubscribed) {
    return <PremiumContent />;
  }
 
  return (
    <View>
      <Text>Unlock Premium Features</Text>
      {packages?.map((pkg) => (
        <Button
          key={pkg.identifier}
          title={`Buy ${pkg.product.priceString}`}
          // Action triggers the native purchase flow
          onPress={() => purchaseSubscription(pkg)}
        />
      ))}
    </View>
  );
};

🎨 useThemeConfig

The useThemeConfig hook is the centralized theme provider for React Navigation. It synchronizes the navigation theme (colors for headers, backgrounds, and text within the navigation stack) with the current theme state managed by NativeWind (light or dark mode).

This hook prevents visual mismatches, ensuring the user sees a seamless, consistent theme across the entire application, from custom components to the navigation headers.

const ThemeProvider = ({ children }) => {
  // Hook returns the correct theme object (DarkTheme or LightTheme)
  const theme = useThemeConfig();
 
  return (
    // The theme is passed directly to the React Navigation container
    <NavigationContainer theme={theme}>{children}</NavigationContainer>
  );
};