A simple and easy to use react library to create fully customizable popups.
- ✨ Features
- 🔎 Example
- 🚚 Installation
- 📚 Documentation
- 🔮 Features that may be implemented in the future
- 📄 License
- Easy to use
- Fully customizable
- Typescript ready
- SSR support
- Lightweight
- ESM and CJS available
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>
);
}
yarn add react-customizable-popup
npm install react-customizable-popup
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>
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
};
root
.
As mentioned earlier, the popup is located at the root of your application. The root of the application often has an id of root
(it is the case with Create React App and Vite with React), but not all the time. For example, if you are using Nextjs, the root id is __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>
);
Here are listed all the props you can use to customize your popup as you wish.
Required: no
Type: string
Default value:
#root
The root of the application, and where the popup will be rendered.
Required: no
Type: ReactElement
Default value: none
The trigger for opening the popup.
See Usage.
forwardRef
on your component.
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.
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
.
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
.
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
.
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.
Required: no
Type: number
Default value:
12
The size of the arrow in pixels.
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.
Required: no
Type: string
Default value: none
The class(es) to apply to the popup.
Required: no
Type: string
Default value: none
The class(es) to apply to the popup backdrop.
Required: no
Type: number
Default value:
12
The distance from the popup to the toggler in pixels.
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.
Required: no
Type: boolean
Default value:
true
If the popup component is rendered with a react portal at the root
of the application.
Required: no
Type: () => void
Default value: none
A function that runs at the opening of the popup.
Required: no
Type: () => void
Default value: none
A function that runs at the closing of the popup.
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.
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.
- Support for CSS-in-JS
MIT © Colin Lienard