Install
With npm
Install
npm i @viivue/easy-popup
..then import
// style
import "@viivue/easy-popup/dist/easy-popup.min.css"
// script
import "@viivue/easy-popup";
View package at @viivue/easy-popup
With CDN
<!-- Easy Popup -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/viivue/easy-popup@1.2.0/dist/easy-popup.min.css">
<script src="https://cdn.jsdelivr.net/gh/viivue/easy-popup@1.2.0/dist/easy-popup.min.js"></script>
Use
Default init
With attribute
Value of the attribute will be treated as the popup's ID.
<div data-easy-popup="popup-1">
<!-- Popup content -->
<h2>Popup #1</h2>
<p>Lorem ipsum dolor sit amet hendrerit nec neque ultricies.</p>
</div>
...then you can use the popup's ID as the URL to View popup.
<a href="#popup-1">Open Popup #1</a>
With JSON
Initialize your popup with more options without touching the JavaScript file. View popup.
<div data-easy-popup='{"id": "my_popup"}'>
<!-- Popup content -->
</div>
Make sure the script always execute after the HTML has been loaded. Or run
EasyPopup.init()anytime the HTML is ready.
Custom init
Init anytime with JavaScript. View popup.
<div class="your-class">
<!-- Popup content -->
</div>
EasyPopup.init('.your-class', {
id: 'popup-js',
// more options here
});
Toggle popup with [data-ep-toggle="id"]
An alternative way to toggle a popup:
<button data-ep-toggle="popup-3">Open popup</button>
A popup with adding multiple class with option outerClass. Click : and inspect to see in .easy-popup
<button data-ep-toggle='popup-4'>Open popup</button>
Layouts
Layout could be customized with these provided options.
| Description | Option | Buttons |
|---|---|---|
| Use custom layout on mobile | hasMobileLayout: true | View popup |
| Display popup on the sides | theme: "left-side" or theme: "right-side" | Left side, Right side |
| Change the close button text | closeButtonInnerText: "CLOSE" | View popup |
autoShow
- Show popup after page loaded:
autoShow: true - Show popup 3000ms after page loaded:
autoShow: 3000
cookie
Requires PiaJs v0.0.4 or later.
Show popup once and not showing again after a period of time.
- Popup re-appears after 7 days:
{autoShow:true, cookie: 7} - Popup re-appears after 30 days:
{autoShow:true, cookie: "30 days"} - Popup re-appears after 8 hours:
{autoShow:true, cookie: "8 hours"}
Show popup for a number of times and reset after a period of time.
- Shows 3 times, then re-appears after 7 days:
{autoShow:true, cookie: 7, showingTimes: 3}
Remove/clear cookie
To stop using cookie to control a popup, simply change the init options:
{autoShow:false}: prevent the popup reappears, however, the cookie still exists in the client devices.{cookie:undefined}: clear cookie if any.
Or use method:
const popup = EasyPopup.get('my-popup');
popup.cookie.remove(); // remove the cookie data completely
Update/reset cookie
Once the popup with cookie has been init, the only way to update the cookie is to set a new name for the cookie.
Useful when you want to reset the cookie expiration, or set new expiration.
{cookie:"new_expiration_value", cookieName:"new_name"}
Test cookie
You can use Pia.test() to see cookie info.
const popup = EasyPopup.get('my-popup');
console.log(Pia.test(popup.cookie.key));
Cookie demo
View demo code
<div data-easy-popup='{"id": "popup-cookie", "autoShow": "true", "cookie": "1 day", "showingTimes": "5"}'>
<!-- Popup content -->
</div>
API
Options
| Attribute | Type | Default | Description |
|---|---|---|---|
id | string | Auto-generated ID | Set an ID for this popup |
theme | string | default | Other layouts: right-side |
hasMobileLayout | boolean | false | Enable mobile layout (theme options will not work when mobile layout is active) |
mobileBreakpoint | number | 768 | Activate mobile layout when the screen size is <=768px |
closeButtonInnerText | string | svg/icon | Custom innerText of the close button |
triggerSelector | CSS selector | "" | Click on this trigger will also toggle the popup |
outerClass | string | "" | Extra classes to popup outer .easy-popup, use white space for multiple classes, e.g. "class1 class2" |
activeHtmlClass | string | "" | Extra class to <html> when a popup opens |
keyboard | boolean | true | Close popup by pressing ESC key |
clickOutsideToClose | boolean | true | Click on empty outside an opening open will close the popup |
preventScroll | boolean | true | Prevent page scroll when popup is open |
scrollbarWidth | number | undefined | You mostly don't need this unless the page scroller is not the body tag. Set the scrollbar width manually to avoid page jumping when open a popup, only works for preventScroll:true. |
autoShow | boolean or number (ms) | false | true to show the popup right after page loaded, set number for delay, e.g. 1000 for 1000ms after init |
cookie | string or number | undefined | Requires autoShow:true. Set expiration for a popup. Use PiaJs expires. |
showingTimes | number | 1 | Requires cookie. Show n times before expiration day, only works with cookie |
cookieName | string | "" | Requires cookie. Name of the cookie, change name will also lose access to the previous cookie => treat as a new cookie |
Deprecated options
| Attribute | Type | Default | Description |
|---|---|---|---|
title | string | "" | Title for mobile layout |
closeButtonHTML | string | "" | Inner text for close button |
Events
| Name | Description |
|---|---|
open | On popup open |
close | On popup close |
// init
EasyPopup.init('.popup', {
id: 'my-popup',
// assign listener when init
onOpen: data => {
console.log('Popup open', data);
}
});
// get instance
const popup = EasyPopup.get('my-popup');
// listen to an event after init
popup.on('close', data => {
console.log('Popup close', data);
});
Open console log to see data changes on event fires. View popup.
Methods
Global methods
| Name | Description |
|---|---|
EasyPopup.init(selector, options) | Init a popup |
EasyPopup.get(popupId) | Get a popup instance |
EasyPopup.setDev(isDev) | Enable/disable dev mode to see console logs. |
Instance methods
| Name | Description |
|---|---|
instance.open() | Open the popup |
instance.close() | Close the popup |
instance.toggle() | Toggle the popup |
instance.on(eventName, callback) | Assign events with callback |
// get instance
const popup = EasyPopup.get('my-popup');
// open popup
popup.open();
FAQ
1. The page got jumping when the popup is shown. How to fix it?
You need to understand how preventScroll works in Easy Popup. When you enable the preventScroll option:
- Easy Popup adds an
ep-prevent-scrollclass to the<body>.- This sets
overflow: hiddento prevent page scrolling.
- This sets
- Hiding the scrollbar can cause the page to shift right.
- To prevent shifting, Easy Popup adds
padding-rightto the<body>.- The padding is equal to the scrollbar width.
- The scrollbar width is auto-calculated by JavaScript.
- Note: This may not be 100% accurate across all browsers/devices.
Easy Popup has a built-in function to calculate the scrollbar width automatically depending on the browser/device. However, this may not work as expected in some cases.
For optimal results:
- Set the scrollbar width via CSS.
- Use the same value for the
scrollbarWidthoption in Easy Popup.
/* custom scrollbar */
/* Works on Chrome, Edge, and Safari */
body::-webkit-scrollbar {
width:8px;
}
body::-webkit-scrollbar-track {
background:#ccc;
}
body::-webkit-scrollbar-thumb {
background-color:#000;
}
Easy Popup options
{
"preventScroll": true,
"scrollbarWidth": 8
}
Note: On touch screen, the scrollbar width is set to 0 automatically.
Development
Clone this repo, then:
# install
npm i
# run dev server
npm run dev
Publish
# build
npm run prod
# test package before publish
npm pack
# publish package (search & replace old version number)
npm publish
Contribute
Feel free to submit new issue or create a pull request.
Branches:
main: for publishing (handled by Netlify at https://easy-popup.netlify.app/)staging: for development deploy (handled by GitHub Pages at https://viivue.github.io/easy-popup/)gh-pages-staging: for deploying staging branch
Licence
MIT (c) 2023 ViiVue.