Popzy.js

Try It Out

Popzy is a lightweight modal library built with pure JavaScript. (Source code available on GitHub)

• No dependencies
• Fully customizable with CSS
• Supports CSS transitions
• Simple and intuitive API
• No extra files needed
• Optimized for user experience

Here are some examples of how to use Popzy:

Basic Modal Modal with Buttons Large Content Modal Footer-Only Close Modal Persistent Modal (Stays in DOM) Multiple Modals YouTube Embed Modal

Installation

Method	Steps
Direct Download	Download ZIP Simply extract the ZIP file and use the popzy.min.js and popzy.min.css files in your project.

Popzy provides a small CSS file that you can include directly via a CDN link. This makes it easy to integrate into your project and customize as needed.

Include the Popzy JavaScript file in your project:

<script src="https://cdn.jsdelivr.net/gh/phamhuy15/popzy/popzy.min.js"></script>

Optionally, include the Popzy CSS file for default styling:

<link
        rel="stylesheet"
        href="https://cdn.jsdelivr.net/gh/phamhuy15/popzy/popzy.min.css"
    >

You can explore the list of CSS classes used by Popzy in the Styling section to easily customize them as needed.

You can use the released versions of Popzy available here.

Usage

// Initialize a new modal
    const modal = new Popzy({
        content: '<h1>This is content</h1>',
        // templateId: 'my-modal-template',
        footer: true,
        destroyOnClose: false,
        closeMethods: ['overlay', 'button', 'escape'],
        cssClass: ['custom-class-1', 'custom-class-2'],
        onOpen: function() {
            console.log('Modal opened');
        },
        onClose: function() {
            console.log('Modal closed');
        },
    });
    
    // Set modal content
    modal.setContent('<h1>This is new content</h1>');
    
    // Add footer buttons
    modal.addFooterBtn('Cancel', 'btn btn--default', function(e) {
        modal.close();
    });
    
    modal.addFooterBtn('Confirm', 'btn btn--primary', function(e) {
        modal.close();
    });
    
    // Open the modal
    modal.open();
    
    // Close the modal
    modal.close();

If you use templateId, ensure that a <template> element with the corresponding id exists in your HTML. Below is an example:

    <template id="my-modal-template">
        <div>
            <h1>This is modal content</h1>
            <p>You can add any HTML here.</p>
        </div>
    </template>
    
    

Note: When using templateId, do not provide content. If both are specified, content will take precedence, and templateId will be ignored.

Options

Option	Type	Description
content, templateId	string	One of content or templateId is required to set the modal content. content accepts an HTML string, while templateId specifies the ID of a template element. If both are provided, content will take precedence.
cssClass	array	Custom CSS classes applied to the modal container (default: [])
footer	boolean	Shows a footer in the modal (default: false)
destroyOnClose	boolean	Decides whether the modal is removed from the DOM upon closing (default: true)
closeMethods	array	Defines methods to close the modal (default: ['overlay', 'button', 'escape'])
enableScrollLock	boolean	Enables or disables scroll locking when the modal is open. When set to true, it prevents scrolling on the target element specified by scrollLockTarget. Default: true.
scrollLockTarget	function	A callback that returns the element to apply scroll locking on. By default, it locks scrolling on document.body.
onOpen	function	Callback function executed when the modal opens (after transition ends) (default: undefined)
onClose	function	Callback function executed when the modal closes (default: undefined)

Styling

Popzy styles are defined in CSS. You can fully customize it to meet your design requirements.

Class Name	Description/Role
.popzy	Styles the backdrop overlay for the modal. Handles positioning, centering the modal, and applying a semi-transparent background.
.popzy--show	Applied when the modal is visible. Controls the visibility and opacity of the backdrop.
.popzy__container	Styles the modal container, including its size, padding, border-radius, and transform animations for scaling in/out.
.popzy__close	Styles the close button inside the modal, including its size, position, and hover effects.
.popzy__content	Handles the modal's main content area, including scrollable behavior with a maximum height.
.popzy__footer	Styles the modal footer, aligning buttons to the right and adding spacing between them.
.popzy--no-scroll	Disables scrolling on the target element specified by scrollLockTarget when the modal is open.

For more details, you can view the full CSS file directly here: popzy.css.

API

Method	Description
open()	Opens the modal and triggers the onOpen callback.
close()	Closes the modal and triggers the onClose callback. If close(true) is called, it behaves the same as destroy(), removing the modal from the DOM.
setContent(content)	Updates the modal content.
setFooterContent(content)	Updates the footer content.
addFooterBtn(label, cssClass, callback)	Adds a button to the footer with a callback function.
destroy()	Completely removes the modal elements from the DOM and unbinds all associated events.