💬 react-customizable-popup
A simple and easy to use react library to create fully customizable popups.
📋 Table of content
-
✨ Features -
🔎 Example -
🚚 Installation -
📚 Documentation -
📄 License
✨ Features
- Easy to use
- Fully customizable
- Typescript ready
- SSR support
- Lightweight
- ESM and CJS available
🔎 Example
See the demo.
import Popup from 'react-customizable-popup';
const App = () => {
return (
<Popup
toggler={<button>Open this popup</button>}
position={['center', 'top']}
/* Lots of other props */
>
<button data-close>Close this popup</button>
{/* Your content */}
</Popup>
);
}
🚚 Installation
Using Yarn
yarn add react-customizable-popupUsing NPM
npm install react-customizable-popup
📚 Documentation
Basic usage
To create a popup, import the package into your file and add a Popup component. This one has an important prop, it's toggler. This prop corresponds to an element that will trigger the opening of the popup. The content of the popup is simply the children of the Popup component.
import Popup from 'react-customizable-popup';
const App = () => {
return (
<Popup toggler={<button>Open this popup</button>}>
{/* Your content */}
</Popup>
);
};If you test this code, you will see that your toggler is present. The popup is located at the root of your application. When you click on your toggler, the popup will appear on top of all the other elements, along with an optional backdrop that allows you to close the popup by clicking on it.
You can also add an element (like a cross for example) inside the popup to close it. To do this, add the attribute data-close to your element.
<Popup some-props>
<button data-close>Close this popup</button>
{/* Your content */}
</Popup>Usage without a toggler
If you don't want any toggler for your popup (because you want to open it after a condition for example), you can omit the toggler prop and instead use a ref on the popup to access its methods. These methods are open, close and toggle.
import Popup from 'react-customizable-popup';
const App = () => {
const popupRef = useRef(null);
useEffect(() => {
if (popupRef.current) {
setTimeout(() => popupRef.current.open(), 2000); // Open the popup after 2 seconds
}
}, []);
return (
<Popup ref={popupRef}>
{/* Your content */}
</Popup>
);
};If you use Typescript, you can do the following :
import Popup, { PopupHandle } from 'react-customizable-popup';
const App = () => {
const popupRef = useRef<PopupHandle>(null);
// And then the same thing
};Globally set the root
root.
As mentioned earlier, the popup is located at the root of your application. The root of the application often has an id equal to root (it is the case with Create React App), but not all the time. For example, if you are using Nextjs, the root has a value of __next.
To specify the root, you can set the root prop on each popup, but this is not ideal if you use many popups in your application. You can therefore set the root globally by using a context. In your app.jsx or main.jsx, add the PopupProvider around your app and set the root.
import { PopupProvider } from 'react-customizable-popup';
ReactDOM.render(
<PopupProvider root="your-root-id">
<App />
</PopupProvider>,
document.getElementById('your-root-id'), // It should be the same
);If you are using Nextjs, you can do the following in your _app.jsx file.
import { PopupProvider } from 'react-customizable-popup';
const App = ({ Component, pageProps }) => (
<PopupProvider root="__next">
<Component {...pageProps} />
</PopupProvider>
);Props
Here are listed all the props you can use to customize your popup as you wish.
root
Required: no
Type: string
Default value:
#root
The root of the application, and where the popup will be rendered.
toggler
Required: no
Type: ReactElement
Default value: none
The trigger for opening the popup.
See Usage.
forwardRef on your component.
toggleOn
Required: no
Type: 'click' | 'hover'
Default value:
'click'
The way to trigger the opening of the popup.
The popup will open either when the toggler is clicked or when the mouse hovers over the toggle. If hover is chosen, the backdrop prop will be set to false.
position
Required: no
Type: [
'center' | 'left' | 'midleft' | 'right' | 'midright',
'center' | 'top' | 'midtop' | 'bottom' | 'midbottom',
] | 'modal'
Default value:
['center', 'bottom']
The position of the popup in relation to the toggler.
The first value in the array corresponds to the horizontal axis, and the second corresponds to the vertical axis. Values starting with mid place the popup on an edge of the toggler and make it go beyond the other edge. To understand it better, look at the demo.
If this value is set to modal, the popup is positionned at the center of the screen, regardless of the position of the toggler, and the fixed prop is set to true.
noScroll
Required: no
Type: boolean
Default value:
true
If the scroll is disabled while the popup is open.
false if the prop fixed is set to true.
fixed
Required: no
Type: boolean
Default value:
false
If the popup remains fixed at its opening position at scroll.
true, the prop noScroll will be set to false.
true.
arrow
Required: no
Type: boolean
Default value:
true
If there is an arrow.
The arrow is automatically positioned according to the position of the popup and the toggler. This arrow is easy to style.
arrowSize
Required: no
Type: number
Default value:
12
The size of the arrow in pixels.
backdrop
Required: no
Type: boolean
Default value:
true
If there is a backdrop.
This backdrop appears when the popup is open and allows to close it with a click. It is possible to style this backdrop.
className
Required: no
Type: string
Default value: none
The class(es) to apply to the popup.
backdropClassName
Required: no
Type: string
Default value: none
The class(es) to apply to the popup backdrop.
distanceFromToggler
Required: no
Type: number
Default value:
12
The distance from the popup to the toggler in pixels.
distanceFromEdges
Required: no
Type: number
Default value:
0
The distance from the popup to the edges of the screen.
If the popup is too large and overflows from one side of the screen, its position will be adjusted so that the popup does not overflow. This property corresponds to the minimum distance the popup will have from the edges of the screen so that it will not stick to it.
portal
Required: no
Type: boolean
Default value:
true
If the popup component is rendered with a react portal at the root of the application.
onOpen
Required: no
Type: () => void
Default value: none
A function that runs at the opening of the popup.
onClose
Required: no
Type: () => void
Default value: none
A function that runs at the closing of the popup.
Styling
Applying styles
Styles are set by default and you can keep them if you want, but you can also delete them and set your own. To do this, add the className prop (and/or the backdropClassName prop) and simply customize your popup (and/or your backdrop) with css.
The arrow will inherit the background and border styles from your popup, so you don't have to worry about it. If you want to change its size, look at the arrowSize prop.
Applying animations
The animations are simply css transitions because the popup is never removed from the DOM. The popup is actually hidden by setting opacity to 0. To set animations (and different transitions at the opening and closing of the popup), you can use the open class over your own class.
.my-popup-class {
/* The closing animation */
transform: translateY(1rem);
transition: transform 0.1s ease-in, opacity 0.1s ease-in;
}
.my-popup-class.open {
/* The opening animation */
transform: translateY(0);
transition: transform 0.3s ease-out, opacity 0.3s ease-in;
}:global selector on the open class.
.my-popup-class:global(.open) {
/* ... */
}The backdrop animations work in the same way.
📄 License
MIT © Colin Lienard