Focusly.js: A 2kB Vanilla JavaScript Modal Library

Try It Out

Focusly 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 Focusly:

Installation

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

Focusly 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 Focusly JavaScript file in your project:

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

Optionally, include the Focusly CSS file for default styling:

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

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

Usage

// Initialize a new modal
const modal = new Focusly({
    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.
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`)
cssClass	array	Custom CSS classes applied to the modal container (default: `[]`)

Styling

Focusly styles are defined in CSS, with some positioning handled by JavaScript. You can fully customize it to meet your design requirements.

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

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

API

Method	Description
open()	Opens the modal and triggers the `onOpen` callback.
close()	Closes the modal and triggers the `onClose` callback.
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()	Removes the modal and unbinds all events