Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eveningkid/react-native-popable

Popovers, tooltips for React Native
https://github.com/eveningkid/react-native-popable

alert expo popover react-native tooltip web

Last synced: 14 days ago
JSON representation

Popovers, tooltips for React Native

Awesome Lists containing this project

README 

        
# react-native-popable



Popovers, tooltips for React Native.






🤖 Controlled and uncontrolled popovers



✍️ Customizable popover content (text, views)



🌐 Works on web, hover support



🙅‍♂️ No-dependency



🎒 Built with Typescript



👩‍🔬 Try the [API sandbox](https://snack.expo.io/dmLOIiVHy)



```jsx



  @eveningkid



```



## Usage



```sh

npm install react-native-popable

```



> **If working with React Native Web, you'll need at least version 0.15.0.** It introduced hover events for Pressable which is used internally.



### Popable



Add a popover around a given component. Uses [`Popover`](#Popover) internally.



**Every property coming from `Popover` can be used the exact same way that with `Popable`.**



```jsx

import { Popable } from 'react-native-popable';



export default () => (

  

    @morning_cafe

  

);

```



- [children](#popable.children)

- [content](#content)



- Optional

  - [action](#action)

  - [animated (from Popover)](#animated)

  - [animationType (from Popover)](#animationType)

  - [backgroundColor (from Popover)](#backgroundColor)

  - [caret (from Popover)](#caret)

  - [caretPosition (from Popover)](#caretPosition)

  - [numberOfLines (from Popover)](#numberOfLines)

  - [onAction](#onAction)

  - [position (from Popover)](#position)

  - [strictPosition](#strictPosition)

  - [style](#style)

  - [visible (from Popover)](#visible)

  - [wrapperStyle](#wrapperStyle)



#### Popable.children



What should serve as the popover trigger, basically any React element.



```jsx



  



  @morning_cafe



```



#### content



Popover content: can be a string or any React element (text, views).



If you just want the popover, without all the outside logic that comes from `Popable`, use [`Popover` instead](#popover).



```jsx



      Anything :)

    

  }

>

  @morning_cafe



  @morning_cafe



```



#### action



Upon what action should the popover be shown/dismissed: `press`, `longpress` or `hover` (web-only). **Defaults to `press`.**



```jsx



  @morning_cafe



```



#### onAction



Callback to monitor the popover visibility state. Called whenever `visible` changes (even through `Popover` internal state). Useful for side-effects.



```jsx

 {

    if (visible) {

      Analytics.pressedProfilePopover();

    }

  }}

  content="See profile"

>

  @morning_cafe



```



#### strictPosition



If the popover should be placed on the opposite side when it doesn't fit at the given position. If a popover is on the left of the screen and its position is left, the position will be turned to right by default. If `strictPosition` is `true`, the popover will remain on the left. **Defaults to `false`.**



```jsx



  @morning_cafe



```



#### style



Style the `Popover` component using any [`View` style property](https://reactnative.dev/docs/view-style-props).



```jsx

@morning_cafe

```



#### wrapperStyle



Style the wrapping `View` component using any [`View` style property](https://reactnative.dev/docs/view-style-props).



```jsx

@morning_cafe

```



### Popover



The UI component in `Popable` can also be used on its own.



```jsx

import { Popover } from 'react-native-popable';



export default () => @morning_cafe;

```



- [children](#children)



- Optional

  - [animated](#animated)

  - [animationType](#animationType)

  - [backgroundColor](#backgroundColor)

  - [caret](#caret)

  - [caretPosition](#caretPosition)

  - [forceInitialAnimation](#forceInitialAnimation)

  - [numberOfLines](#numberOfLines)

  - [visible](#visible)

  - [position](#position)



#### children



The popover content: will render text if a string is given or the given React elements otherwise.



```jsx

@morning_cafe



  



```



#### animated



If the popover should animate when the `visible` property changes. **Defaults to `true`.**



```jsx

@morning_cafe

```



#### animationType



If the popover should bounce a little (`spring`) or not (`timing`). **Defaults to `timing`.**



```jsx

@morning_cafe

```



#### backgroundColor



Background color for the popover and the caret.



```jsx

@morning_cafe

```



#### caret



If the little caret (the "half-triangle") should be displayed. **Defaults to `true`.**



```jsx

@morning_cafe

```



#### caretPosition



Position for the caret: `left`, `center` or `right`. **Defaults to `center`.**



```jsx

@morning_cafe

```



#### forceInitialAnimation



If the popover should animate when it renders for the first time. This means that if `visible` is set to `true`, the popover will fade in after it mounted. Likewise, if `visible` is `false`, the popover will fade out. If this property is kept falsy, the popover will be displayed in its initial visibility state, without animating. It is very unlikely you would ever need this property. **Defaults to `false`.**



```jsx

@morning_cafe

```



#### numberOfLines



Limit the number of lines if `children` is a `string`. Corresponds to [`Text.numberOfLines`](https://reactnative.dev/docs/text#numberoflines) which clips text with `...` if the given text is more than a number of lines.



```jsx

@morning_cafe_got_longer

```



#### visible



If the popover should be visible. Will animate every value change if `animated` is `true`.



```jsx

const [visible, setVisible] = useState(false);



@morning_cafe



 {

    setVisible((isVisible) => !isVisible);

  }}

/>

```



#### position



Position for the popover: `top`, `right`, `bottom` or `left`. Changes the caret position. **Defaults to `top`.**



```jsx

@morning_cafe

```



#### ViewProps



Every usual [`View` property](https://reactnative.dev/docs/view#props) is available as well.



```jsx

@morning_cafe

```



### usePopable



If you need to imperatively control the `Popable` component, you can use the `usePopable` hook. It lets you `show` and `hide` the Popable without needing to manage state yourself.



You typically won't need to use this hook, since `react-native-popable` intelligently hides popovers when users press or hover away. However, it comes in handy for features like menus.



#### Usage



```jsx

const [ref, { hide, show }] = usePopable();



return 

```



If you prefer to not use the array syntax, you can destructure like so:



```jsx

const { ref, hide, show } = usePopable();



return 

```



#### Hide the Popable



If you're building a Popable menu, you'll want to `hide` the Popable when someone clicks a menu item.



```jsx

import React from 'react';

import { StyleSheet, View, Text } from 'react-native';

import { Popable, usePopable } from 'react-native-popable';



import Menu from './menu';



export default function App() {

  const [ref, { hide }] = usePopable();



  return (

    

       hide()} />}>

        Open Menu

      

    

  );

}

```



#### Show the Popable



Similar to the example above, you can `show` the Popable imperatively:



```jsx

import React from 'react';

import { StyleSheet, View, Text } from 'react-native';

import { Popable, usePopable } from 'react-native-popable';



import Menu from './menu';



export default function App() {

  const [ref, { show, hide }] = usePopable();



  return (

    

       show()} />



       hide()} />}>

        Menu

      

    

  );

}

```



This is a rare use-case, since you'll typically use the children as the trigger of your Popable.



## Contributing



See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.



## License



MIT © eveningkid