react-native-ios-popover

A react native wrapper component to use the native iOS popover by wrapping a react native view inside a UIViewController and presenting it.

PopoverView Left: Example 1, Example 2, and Right: Example 3, Example 4

PopoverView Left: Example 5, Example 6, and Right: Example 7, Example 8

🚧⚠️ Documentation WIP 🚧⚠️

Re-write in progress (see TODO for updates). See README-old.md for the old version of the documentation.

1. Installation

# 1.1 install via npm...
npm install react-native-ios-popover

# 1.2 ...or install via yarn 
yarn add react-native-ios-popover


# 2.1 install the lib's peer dependency via npm...
npm install react-native-ios-utilities

# 2.2 ...or install the lib's peer dependency via yarn
# Note: See "Installation: Dependencies" section for more details
yarn install react-native-ios-utilities


# 3. then run pod install (uses auto-linking)
cd ios && pod install

1.1 Installation Notes

If you encounter any errors/bugs while using this library, or want a particular feature implemented, please see the troubleshooting section, or create an issue!

Installation: Dependencies

This library depends on react-native-ios-utilities for some of the native functionality (i.e. it uses it as a peer dependency).

If you want to install and use a specific version of this library, please see the Installation: Versions and Compatibility section for more details.

If you are using any other library that uses react-native-ios-utilities (e.g. react-native-ios-context-menu, etc)., then please refer to the version compatibility guide.

Installation: Versions and Compatibility

The library's peer dependency requirements are enforced using semver (i.e. major.minor.patch). If you wish to use a specific version of this library, then please install the corresponding version of react-native-ios-utilities.

📝 Note: As a general rule, the major version should be the same between the library and the dependency. For example, if you're using [email protected], then you should install [email protected], etc.

1.2 Troubleshooting

Troubleshooting: Xcode Build Error (Swift)

This library is written in Swift. If you are having trouble building your app after installing this library, try adding an empty swift file:

1. Open up your ios/project.xcworkspace project
2. On the project navigator panel (located on the right side of Xcode), right click on your project group (or another folder/group i.e the blue or yellow icons) and select the "New File..." option
3. In the popup sheet, select "Swift" as the template and then click the "Next" button
4. A "Save As" popup sheet should appear and then click "Create" (you can rename the file first if you want to)
5. If Xcode asks you to create a "Objective-C Bridging Header" choose "Create Objective-C Bridging Header"

Troubleshooting: Cocoapods Static Libraries Error

If you encounter the following error when running pod install:

[!] The following Swift pods cannot yet be integrated as static libraries:

The Swift pod `react-native-ios-popover` depends upon `React-Core`, which does not define modules. To opt into those targets generating module maps (which is necessary to import them from Swift when building as static libraries), you may set `use_modular_headers!` globally in your Podfile, or specify `:modular_headers => true` for particular dependencies.

Then try following these steps:

1. Open up your project's ios/podfile configuration
2. Under target 'ProjectName' do block, find the 'React-Core' pod, and append the following snippet to the end of the line: , :modular_headers => true
3. It should now look something similar to this: pod 'React-Core', :path => '../node_modules/react-native/', :modular_headers => true
4. Try running pod install again.

2. Usage

Please check out the examples section or the examples directory for more on how to use it.

import { PopoverView } from "react-native-ios-popover";

function PopoverViewExample() {
  const popoverRef = useRef();

  return (
    <PopoverView
      ref={popoverRef}
      renderPopoverContent={() => (
        <View style={{padding: 20}}>
          <Text>
            {'Popover Content'}
          </Text>
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        popoverRef.current.toggleVisibility();
      }}>
        <Text>
          {'Toggle Popover Visibility'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

3. Documentation

3.1 Modules/Components

PopoverView Component

PopoverView Component: Props

PopoverView Component: Events

PopoverView Component: Functions

3.2 Objects and Types

📄 PopoverRelatedTypes.ts

• 📌 Declaration: PopoverRelatedTypes.ts

String Union: PopoverSize

This type is used in the PopoverView component's popoverSize prop. Use this type to control the size of the popover.

String Union: ArrowDirections

This type is used to for the PopoverView component's permittedArrowDirections prop. This type corresponds to the UIPopoverArrowDirection swift struct, check out the apple docs for more info.

4 Examples

Check out the examples directory. The example app contains a bunch of demos that showcases the different PopoverView configurations, props and events you can use. The assets directory contains gifs and screenshots for every example/test shown in the example app.

• Note: the section title on each example contains a link to the corresponding example code.

1. Clone the repository: git clone https://github.com/dominicstop/react-native-ios-popover.git
2. cd react-native-ios-popover && yarn bootstrap
3. Go to the react-native-ios-context-popover/example directory and run yarn ios to build/launch the example app in the iOS simulator.

4.1 PopoverView Examples

PopoverView Example 01

A bare minimum example showing how to present a popover via the setVisibility function.

🔗 Full Example

function PopoverViewExample01() {
  const popoverRef = useRef();

  return (
    <PopoverView
      // get/store a ref to the popover component
      ref={popoverRef}
      // a function that returns the content to show
      // inside the popover
      renderPopoverContent={() => (
        <View style={{padding: 20}}>
          <Text>
            {'Popover Content'}
          </Text>
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        // show the popover when the button is pressed
        // (note: `setVisibility` will throw an error if attempting to 
        // show a popover that's already visible)
        // alt. you can call `toggleVisibility` to show/hide the popover
        popoverRef.current.setVisibility(true);
      }}>
        <Text>
          {'Show Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

PopoverView Example 02

A example PopoverView for the permittedArrowDirections prop.

• This prop accepts an array of ArrowDirections string values (e.g: 'up', 'down', etc). You can also pass in an empty array or null to specify that the popover should not have an arrow.
• The popover position and sizing will automatically adapt based on the permittedArrowDirections.

🔗 Full Example

function PopoverViewExample02() {
  const popoverRef = useRef();
  
  return(
    <PopoverView
      ref={popoverRef}
      // the allowed direction of the popover arrow.
      // accepts an array of `ArrowDirections` values,
      // e.g. "up", "down", etc.
      permittedArrowDirections={["left"]}
      renderPopoverContent={() => (
        <View style={{padding: 20}}>
          <Text>
            {'Left Arrow'}
          </Text>
        </View>
      )}
      >
      <TouchableOpacity onPress={() => {
        popoverRef.current.setVisibility(true);
      }}>
        <Text>
          {'Show Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

PopoverView Example 03

A example PopoverView with the popoverSize prop set to STRETCH.

• By default, the popoverSize prop is set to INHERIT which means the size of the popover is determined by the size of the popover content.
• However, if you set the prop to STRETCH, the popover will be sized to be as big as possible based on the permittedArrowDirections prop, its position on screen, etc.

🔗 Full Example

function PopoverViewExample03() {
  const popoverRef = useRef();

  return(
    <PopoverView
      ref={popoverRef}
      // set the `popoverSize` prop to `STRETCH` to make the
      // popover as big as possible.
      popoverSize={{type: 'STRETCH'}}
      // You also have to set `popoverCanOverlapSourceViewRect`
      // prop to false to prevent the popover from covering up
      // the popover source view.
      popoverCanOverlapSourceViewRect={false}
      permittedArrowDirections={["up", "down"]}
      // the style of the root popover content view must be set
      // to `{flex: 1}` so that it'll stretch to the size of the
      // popover.
      renderPopoverContent={() => (
        <View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
          <Text>
            {'Popover Content'}
          </Text>
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        popoverRef.current.setVisibility(true);
      }}>
        <Text>
          {'Show Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

PopoverView Example 04

A example PopoverView with the popoverBackgroundColor prop set to "pink". By default, the PopoverView has a transparent background with a blur effect.

🔗 Full Example

function PopoverViewExample04(props) {
  const popoverRef = useRef();

  return (
    <PopoverView
      ref={popoverRef}
      // pass in a valid color value
      popoverBackgroundColor={'pink'}
      renderPopoverContent={() => (
        <View style={{padding: 20}}>
          <Text>
            {'Popover Content'}
          </Text>
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        popoverRef.current.setVisibility(true);
      }}>
        <Text>
          {'Show Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

PopoverView Example 05

A example PopoverView for programmatically hiding the popover via the setVisibility function.

• The setVisibility(bool) function will throw an error if it's already visible or hidden.

🔗 Full Example

function PopoverViewExample05(props) {
  const popoverRef = useRef();

  return (
    <PopoverView
      ref={popoverRef}
      onPopoverDidHideViaTap={() => alert('onPopoverDidHideViaTap')}
      renderPopoverContent={() => (
        <View style={{padding: 20}}>
          <TouchableOpacity onPress={() => {
            // hide the popover
            popoverRef.current.setVisibility(false);
          }}>
            <Text>
              {'Dismiss Popover'}
            </Text>
          </TouchableOpacity>
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        // toggle popover visibility
        popoverRef.current.toggleVisibility();
      }}>
        <Text>
          {'Toggle Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

PopoverView Example 06

A simple PopoverView example for the popover did show/hide events.

🔗 Full Example

function PopoverViewExample06(props) {
  const popoverRef = useRef();

  return(
    <PopoverView
      ref={popoverRef}
      // popover events
      onPopoverDidHide={() => alert('onPopoverDidHide')}
      onPopoverDidShow={() => alert('onPopoverDidShow')}
      renderPopoverContent={() => (
        <View style={{padding: 20}}>
          <Text style={styles.popoverText}>
            {'Popover Content'}
          </Text>
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        popoverRef.current.setVisibility();
      }}>
        <Text>
          {'Toggle Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

4.1.7 PopoverView Example 07

A example PopoverView that has a switch that toggles the popoverShouldDismiss prop.

• The onPopoverDidAttemptToDismiss prop is set to true by default. This prop controls whether or not the popover should dismiss when there's a tap gesture outside the popover.
• So setting the onPopoverDidAttemptToDismiss to false will prevent the popover from dismissing via a tap outside the popover.

🔗 Full Example

function PopoverViewExample07(props) {
  const popoverRef = useRef();
  
  const [isEnabled, setIsEnabled] = useState(false);
  // toggle `popoverShouldDismiss`
  const toggleSwitch = () => setIsEnabled(previousState => !previousState);

  return(
    <PopoverView
      ref={popoverRef}
      // set the `popoverShouldDismiss` prop
      popoverShouldDismiss={isEnabled}
      onPopoverDidAttemptToDismiss={() => alert('onPopoverDidAttemptToDismiss')}
      renderPopoverContent={() => (
        <View>
          <Text>
            {'popoverShouldDismiss'}
          </Text>
          <Switch
            onValueChange={toggleSwitch}
            value={isEnabled}
          />
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        popoverRef.current.setVisibility(true);
      }}>
        <Text>
          {'Show Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

PopoverView Example 08

A example PopoverView for the toggleVisibility function.

🔗 Full Example

function PopoverViewExample08(props) {
  const popoverRef = useRef();

  return(
    <PopoverView
      ref={popoverRef}
      popoverShouldDismiss={false}
      renderPopoverContent={() => (
        <View style={{padding: 20}}>
          <Text>
            {'Popover Content'}
          </Text>
        </View>
      )}
    >
      <TouchableOpacity onPress={() => {
        // toggle the popover visibility
        popoverRef.current.toggleVisibility();
      }}>
        <Text>
          {'Toggle Popover'}
        </Text>
      </TouchableOpacity>
    </PopoverView>
  );
};

License

MIT

Links

• I'm @DominicGo on twitter if you have any questions ✨
• Other libraries: react-native-ios-modal, react-native-ios-context-menu
• This library was generated/made using @react-native-community/bob