nss_libs - NssModal

An animated full-screen modal with customizable content. NUI

Getting Started

NssModal provides a backdrop overlay with a slide-in content container. It supports keyboard and backdrop close, and intelligently prevents closing when the user is typing in an editable field.

import {NssModal} from "nui://nss_libs/ui/NssModal/NssModal.js";

const content_el = document.createElement('div');
content_el.innerHTML = '<h1>Hello World</h1>';

const modal = new NssModal();
modal
    .closeOnModal()
    .closeOnEscape()
    .setContent(content_el)
    .onClose(() => { console.log('Modal closed'); })
    .show();

Constructor

new NssModal()

Creates a new modal instance. No DOM is created until show() is called.

const modal = new NssModal();

Methods

.setContent(content_el)

Sets the HTML element to display inside the modal.

Param	Type	Default	Description
content_el	HTMLElement	—	The content element to wrap in the modal

Returns NssModal — the instance for chaining.

const form_el = document.getElementById('form');
modal.setContent(form_el);

---

.show()

Creates the modal DOM and displays it with a slide-in animation. Plays NssAudio.playSfxShowMenu(0.5).

Returns Promise<void> — resolves when the animation completes.

modal.setContent(content_el).show().then(() => {
    console.log('Modal is fully visible');
});

---

.hide()

Plays the slide-out animation, fires the onClose callback, and destroys the DOM. Plays NssAudio.playSfxHideMenu1(0.5).

Returns Promise<void> — resolves when the animation completes and the DOM is removed.

modal.hide().then(() => {
    modal = null;
});

---

.onClose(callback)

Registers a callback that fires when the modal is closed (by any method: backdrop, keyboard, or hide()).

Param	Type	Default	Description
callback	function	—	Called when the modal closes

Returns NssModal — the instance for chaining.

modal.onClose(() => {
    nss_client.close();
});

---

.closeOnModal()

Enables closing the modal by clicking the backdrop (outside the content).

Returns NssModal — the instance for chaining.

modal.closeOnModal().show();

---

.closeOnEscape()

Enables closing the modal by pressing the Escape key.

Returns NssModal — the instance for chaining.

modal.closeOnEscape();

---

.closeOnBackspace()

Enables closing the modal by pressing the Backspace key.

Returns NssModal — the instance for chaining.

modal.closeOnBackspace();

---

.closeOnKeys(keys)

Enables closing the modal by pressing any of the specified keys.

Param	Type	Default	Description
keys	string[]	—	Array of KeyboardEvent.key values (e.g. ['Escape', 'Backspace'])

Returns NssModal — the instance for chaining.

modal.closeOnKeys(['Escape', 'Backspace', 'q']);

---

.hasContent()

Checks if content has been set.

Returns boolean.

if (!modal.hasContent()) {
    modal.setContent(fallback_el);
}

Events / Callbacks

• onClose — fires when the modal is closed by any method. Register via onClose(callback).
• Keyboard close — intelligently ignores key presses when the user is focused on an editable element (input, textarea, contenteditable, select).
• Audio — NssAudio.playSfxShowMenu(0.5) on open, NssAudio.playSfxHideMenu1(0.5) on close.

CSS

Classes

Class	Description
.nss-modal	Full-screen backdrop overlay.
.nss-modal--out	Fade-out animation state.
.nss-modal-content	Centered content container.
.nss-modal-content--out	Slide-out animation state.

Custom Properties

Property	Default	Description
--nss-modal-anim-dur	500ms	Animation duration. Defined on :root.

Animations

Keyframe	Description
nss-modal-anim__fade-in / fade-out	Backdrop opacity animation.
nss-modal-anim__slide-in-top / slide-out-bottom	Content slide animation.

Dependencies

• NssUiComponent — base class (initializes NssResponsive).
• NssAudio — open/close sound effects.

Things to Know

• Keyboard close (Escape, Backspace) is smart: it checks if the active element is editable before closing. This prevents accidentally closing the modal while typing in a form field.
• The animation wait includes a 100ms buffer on top of the CSS --nss-modal-anim-dur value.
• The modal DOM is fully destroyed on hide() — you need to create a new instance to show it again.
• All configuration methods (closeOnModal, closeOnEscape, setContent, onClose) can be chained before calling show().