react-native-popper

Create fully customizable popovers and tooltips.

Tooltip Example - (CodeSandbox - as we need react-native-web 0.15+ for hover events.)

Features

Includes Popover and Tooltip.
Fully customizable.
Can be controlled or uncontrolled.
Handles focus trap, autofocus and dismiss on Escape on web.
Shifts accessibility focus to first item on Android and iOS.
Has "multiple" mode which can be used to open multiple popovers.

Install

# yarn
yarn add react-native-popper

# npm
npm i react-native-popper

Import

import { Popover, Tooltip } from 'react-native-popper';

Usage

Uncontrolled

Popover:

<Popover
  trigger={
    <Pressable>
      <Text>Press me</Text>
    </Pressable>
  }
>
  <Popover.Backdrop />
  <Popover.Content>
    <Popover.Arrow />
    <Text>Hello World</Text>
  </Popover.Content>
</Popover>

Tooltip:

<Tooltip
  trigger={
    <Pressable>
      <Text>Press me</Text>
    </Pressable>
  }
>
  <Tooltip.Content>
    <Tooltip.Arrow />
    <Text>Hello World</Text>
  </Tooltip.Content>
</Tooltip>

Controlled

Popover:

const [isOpen, setIsOpen] = React.useState(false);

return (
  <Popover
    isOpen={isOpen}
    onOpenChange={setIsOpen}
    trigger={
      <Pressable>
        <Text>Press me</Text>
      </Pressable>
    }
  >
    <Popover.Backdrop />
    <Popover.Content>
      <Popover.Arrow />
      <Text>Hello World</Text>
    </Popover.Content>
  </Popover>
);

Tooltip:

const [isOpen, setIsOpen] = React.useState(false);

return (
  <Tooltip
    isOpen={isOpen}
    onOpenChange={setIsOpen}
    trigger={
      <Pressable>
        <Text>Press me</Text>
      </Pressable>
    }
  >
    <Tooltip.Content>
      <Tooltip.Arrow />
      <Text>Hello World</Text>
    </Tooltip.Content>
  </Tooltip>
);

API

Popover or Tooltip

Prop	Type	Default	Description
trigger (Required)	React Element or Ref	-	Element or ref which will be used as a Trigger
on	"press", "longpress", "hover"	"press" for Popover "hover for Tooltips"	The action type which should trigger the Popover
isOpen	boolean	false	Useful for controlled popovers
onOpenChange	(isOpen: boolean) => void	-	Use this to listen change events. Also to set state for controlled popovers.
onRequestClose	() => void	-	Use this to handle hardware back button press. Similar to React Native Modal's onRequestClose
defaultIsOpen	boolean	false	Specifies initial visibility of popover
placement	string	bottom	"top", "bottom", "left", "right", "top left", "top right", "left top", "left bottom", "right top", "right bottom", "bottom left", "bottom right"
shouldOverlapWithTrigger	boolean	false	Whether the popover should overlap with trigger
placement	string	bottom	"top", "bottom", "left", "right", "top left", "top right", "left top", "left bottom", "right top", "right bottom", "bottom left", "bottom right"
offset	number	0	Distance between popover and trigger's main axis
animated	boolean	true	Determines whether the content should animate
animationEntryDuration	number	150	Duration of entry animation
animationExitDuration	number	150	Duration of exit animation
crossOffset	number	0	Distance between popover and trigger's cross axis
shouldFlip	boolean	true	Whether the popover should flip if there's less space.
mode	'single' \| 'multiple'	'single'	If you need to render multiple popovers at once on Android/iOS, use 'multiple' option. Note - Accessibility focus won't be shifted in this case. Refer mode section
isKeyboardDismissable (Web only)	boolean	true	Determines whether popover can be dismissed with Escape key on web
shouldCloseOnOutsideClick (Web only)	boolean	true	Determines whether popover can be dismissed when clicked outside of popover content and trigger.
autoFocus (Web only)	boolean	true	Shifts focus to first focusable element on web.
trapFocus (Web only)	boolean	true	Traps focus into the opened popover
restoreFocus (Web only)	boolean	true	Restores focus to the triggered element

Popover.Backdrop or Tooltip.Backdrop

Renders a Pressable component. Useful to add click outside to close functionality.
Accepts all Pressable Props.

Popover.Content or Tooltip.Content

Pass the popover content as children here.
Accepts accessibilityLabel prop. This will be announced by the screenreader when popup opens.

Popover.Arrow or Tooltip.Arrow

Props	Type	Required	Default	Description
height	number	No	10	Arrow height
width	number	No	16	Arrow width
style	ViewStyle	No	-	Style will be passed to the View which is used as Arrow
children	ReactNode	No	-	Supply custom Arrow. You pass anything square. Refer CustomArrowExample

OverlayProvider

When using mode="multiple" or Tooltip, we use custom Portal to prevent shifting accessibility focus when opened. To use this Portal, we need to wrap the app with OverlayProvider.

import { OverlayProvider } from 'react-native-popper';

function App() {
    return <OverlayProvider>{/*Your app*/}</OverlayProvider>
}

Phew, That's it!

Why not always use a custom Portal instead of RN's built in Modal?

RN's built in Modal shifts accessibility focus to the first element when it opens. This is hard to achieve using a custom Portal.
Tooltips don't need to shift accessibility focus.
Thus,
On Web, we use ReactDOM's Portal in all cases.
On Android/iOS,
- For Popovers, defaults to RN modal (can be overriden via mode prop. Needs OverlayProvider).
- For Tooltips, defaults to custom Portal (Needs OverlayProvider)

Why are Popover and Tooltip separate components?

Reason: Different Accessibility requirements.

For Tooltips, we add aria-describedby on trigger and role="tooltip" on the Tooltip content and default "on" prop is set to "hover".
- On Android/iOS we use custom Portal, so it doesn't shift accessibility focus.
For Popovers, we add aria-controls on trigger and role="dialog" on it's content. Also, Popover comes with focus trapping options.
- On Android/iOS, we use RN's build in Modal which shifts the accessibility focus to first element. Also, refer mode section

Examples

Checkout examples directory. It has a lot of examples including animations.

cd examples
// Install dependencies
yarn
// web
yarn web
// iOS
yarn iOS
// Android
yarn android

Mode

Mode prop accepts single and multiple values. Defaults to single.
When set to single, it uses RN's built-in Modal which shifts accessibility focus to the first element when opened.
RN's built in modal doesn't support multiple popups at once unless they are nested. If you need multiple popup support without nesting use mode="multiple".
To use mode="multiple", wrap the entire app with OverlayProvider which enables custom Portal like functionality.
I am still figuring out if we can make this simple.

Limitations

Currently we have built in fade animation support. I am still figuring out how we can extract the layout info and use it to provide custom animation config externally. This can be useful when you want to animate depending upon popover content dimensions.

Known issues

When on="hover" is passed and Backdrop is used, it may lead to flickers as Backdrop hijacks pointer events. To mitigate this, either set pointerEvents= "none" on backdrop or remove backdrop completely. I am looking how to handle this in a more simple way.

Accessibility

Web

ARIA attributes

If the mode is set to 'popover', the Popover.Content element has role set to dialog. If the mode is set to 'tooltip', the Popover.Content has role set to tooltip.
The trigger has aria-haspopup set to true to denote that it triggers a popover.
The trigger has aria-controls set to the id of the Popover.Content to associate the popover and the trigger.
The trigger has aria-expanded set to true or false depending on the open/closed state of the popover.

Behaviour

When the popover is opened, focus is moved to the first focusable element inside Popover.Content. If you set autoFocus to false, focus will not return.
When the popover is closed, focus returns to the trigger. If you set restoreFocus to false, focus will not return.
Hitting the Esc key while the popover is open will close the popover. If you set isKeyboardDismissable to false, it will not close.
Focus will be contained within the Popver.Content. If you set trapFocus to false, it will not be contained.

Android/iOS

When mode is set to popover, accessibility focus will be automatically shifted to first element. Check out this demo.

Credits

This library would not exist without useOverlayPosition from React Native ARIA and useOverlayPosition from Adobe's React ARIA.

License

MIT

intergalacticspacehighway/react-native-popper