custom-react-native-popup

A customizable React Native popup component with blur effects and toast integration. This package provides a simple and efficient way to create beautiful popups and modals in your React Native applications.

Features

• 🎨 Customizable Design: Easy to style and customize popup appearance
• 🌫️ Blur Effects: Beautiful blur background using @react-native-community/blur
• 🍞 Toast Integration: Built-in toast message support
• 📱 Responsive: Automatically adapts to different screen sizes
• ⚡ TypeScript Support: Full TypeScript definitions included
• 🔄 Multiple Popups: Support for multiple popups with override functionality
• 🎯 Easy API: Simple hook-based API for React Native
• 🎛️ Dynamic Props: Configurable blur, animation, and styling options

Installation

npm install custom-react-native-popup
# or
yarn add custom-react-native-popup

Dependencies

This package requires the following peer dependencies:

• react >= 16.8.0
• react-native >= 0.60.0

And the following dependencies:

• @react-native-community/blur >= 4.4.0
• react-native-toast-message >= 2.1.7

Usage

Basic Example

import React from 'react';
import { View, Text, Button } from 'react-native';
import { PopupProvider, usePopup, Popup } from 'custom-react-native-popup';

const MyComponent = () => {
  const { showPopup, hidePopup } = usePopup();

  const handleShowPopup = () => {
    showPopup(
      <View style={{ padding: 20 }}>
        <Text>Hello from popup!</Text>
        <Button title="Close" onPress={hidePopup} />
      </View>
    );
  };

  return (
    <View>
      <Button title="Show Popup" onPress={handleShowPopup} />
    </View>
  );
};

const App = () => {
  return (
    <PopupProvider>
      <MyComponent />
      {/* IMPORTANT: Place Popup component at the root level under PopupProvider */}
      <Popup />
    </PopupProvider>
  );
};

export default App;

Advanced Example with Custom Styling

import React from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import { usePopup } from 'custom-react-native-popup';

const AdvancedExample = () => {
  const { showPopup, hidePopup } = usePopup();

  const showCustomPopup = () => {
    showPopup(
      {
        content: (
          <View style={styles.popupContent}>
            <Text style={styles.title}>Custom Popup</Text>
            <Text style={styles.message}>
              This is a custom styled popup with your own content.
            </Text>
            <Button title="Close" onPress={hidePopup} />
          </View>
        ),
        style: styles.customPopup,
        onClickOutside: hidePopup,
      }
    );
  };

  return (
    <View>
      <Button title="Show Custom Popup" onPress={showCustomPopup} />
    </View>
  );
};

const styles = StyleSheet.create({
  popupContent: {
    alignItems: 'center',
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 10,
  },
  message: {
    fontSize: 14,
    textAlign: 'center',
    marginBottom: 15,
  },
  customPopup: {
    backgroundColor: '#f0f0f0',
    borderRadius: 10,
    padding: 20,
  },
});

Dynamic Popup with Custom Props

import React from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import { PopupProvider, usePopup, Popup } from 'custom-react-native-popup';

const DynamicExample = () => {
  const { showPopup, hidePopup } = usePopup();

  const showDynamicPopup = () => {
    showPopup(
      <View style={styles.popupContent}>
        <Text style={styles.title}>Dynamic Popup</Text>
        <Text style={styles.message}>
          This popup uses custom blur, animation, and styling.
        </Text>
        <Button title="Close" onPress={hidePopup} />
      </View>
    );
  };

  return (
    <View>
      <Button title="Show Dynamic Popup" onPress={showDynamicPopup} />
    </View>
  );
};

const App = () => {
  return (
    <PopupProvider>
      <DynamicExample />
      {/* Place Popup component at root level with custom props */}
      <Popup 
        blurAmount={10}
        animationType="slide"
        toastPosition="bottom"
        customStyles={{
          popup: { backgroundColor: '#e8f4fd', borderRadius: 15 },
          overlay: { backgroundColor: 'rgba(0,0,0,0.8)' },
          blur: { backgroundColor: 'rgba(0,0,0,0.3)' }
        }}
      />
    </PopupProvider>
  );
};

const styles = StyleSheet.create({
  popupContent: {
    alignItems: 'center',
    padding: 20,
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 10,
  },
  message: {
    fontSize: 14,
    textAlign: 'center',
    marginBottom: 15,
  },
});

Multiple Popups

import React from 'react';
import { View, Text, Button } from 'react-native';
import { usePopup } from 'custom-react-native-popup';

const MultiplePopupsExample = () => {
  const { showPopup, hidePopup, hideAllPopups } = usePopup();

  const showFirstPopup = () => {
    showPopup({
      id: 'popup1',
      content: <Text>First Popup</Text>,
      onClickOutside: () => hidePopup('popup1'),
    });
  };

  const showSecondPopup = () => {
    showPopup({
      id: 'popup2',
      content: <Text>Second Popup</Text>,
      onClickOutside: () => hidePopup('popup2'),
    });
  };

  return (
    <View>
      <Button title="Show First Popup" onPress={showFirstPopup} />
      <Button title="Show Second Popup" onPress={showSecondPopup} />
      <Button title="Hide All Popups" onPress={hideAllPopups} />
    </View>
  );
};

API Reference

PopupProvider

The provider component that wraps your app and provides popup functionality.

import { PopupProvider } from 'custom-react-native-popup';

const App = () => {
  return (
    <PopupProvider>
      {/* Your app components */}
    </PopupProvider>
  );
};

usePopup Hook

Returns an object with popup management functions.

Methods

• showPopup(content, style?): Shows a popup with the given content
• hidePopup(handler?): Hides popups based on the handler
• hideAllPopups(): Hides all popups
• hideOverrides(): Hides override popups
• getPopupPropsById(id): Gets props for a specific popup
• setPopupPropsById(data): Sets props for a specific popup

Parameters

• content: React node or popup configuration object
• style: Optional custom styles for the popup
• handler: Optional handler for hiding popups (function, string, array, number)

Popup Component

The popup component that renders the popups. Must be placed at the root level under PopupProvider for proper rendering.

Important Placement

The <Popup /> component must be placed at the root level within the <PopupProvider> to ensure proper rendering across your entire application. If placed inside individual components, popups may not render correctly or may be limited to that component's scope.

// ✅ CORRECT - Popup at root level
const App = () => {
  return (
    <PopupProvider>
      <YourAppContent />
      <Popup /> {/* Place here for application-wide popup rendering */}
    </PopupProvider>
  );
};

// ❌ INCORRECT - Popup inside component
const MyComponent = () => {
  return (
    <View>
      <Button onPress={showPopup} />
      <Popup /> {/* Don't place here */}
    </View>
  );
};

Props

interface PopupProps {
  toastConfig?: any;
  blurAmount?: number;                    // Default: 6
  animationType?: 'none' | 'slide' | 'fade';  // Default: 'fade'
  toastPosition?: 'top' | 'bottom';      // Default: 'top'
  toastBottomOffset?: number;             // Default: 20
  customStyles?: {
    blur?: StyleProp<ViewStyle>;
    overlay?: StyleProp<ViewStyle>;
    popup?: StyleProp<ViewStyle>;
  };
}

Usage

import { Popup } from 'custom-react-native-popup';

const App = () => {
  return (
    <PopupProvider>
      <YourAppContent />
      {/* Place Popup component at root level */}
      <Popup 
        blurAmount={8}
        animationType="slide"
        toastPosition="bottom"
        customStyles={{
          popup: { backgroundColor: '#f0f0f0' },
          overlay: { backgroundColor: 'rgba(0,0,0,0.7)' }
        }}
      />
    </PopupProvider>
  );
};

Types

interface PopupConfig<T = Record<string, unknown>> {
  id?: string;
  isVisible: boolean;
  content: React.ReactNode | null;
  style?: StyleProp<ViewStyle>;
  override?: boolean;
  onClickOutside?: (() => void) | null;
  props?: T | null;
}

interface ShowPopupProps<T = Record<string, unknown>> extends PopupConfig<T> {
  isVisible?: boolean;
}

type HidePopupType = (() => void) | string | string[] | number | null | undefined;

interface PopupProps {
  toastConfig?: any;
  blurAmount?: number;
  animationType?: 'none' | 'slide' | 'fade';
  toastPosition?: 'top' | 'bottom';
  toastBottomOffset?: number;
  customStyles?: {
    blur?: StyleProp<ViewStyle>;
    overlay?: StyleProp<ViewStyle>;
    popup?: StyleProp<ViewStyle>;
  };
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.