NssHelper

A static utility class providing common helper functions for NUI components. NUI

Getting Started

NssHelper is a pure static utility class — it is never instantiated directly. Access it via NssResponsive:

const responsive = new NssResponsive();
const helper = responsive.getHelper();

// Or from any NssUiComponent subclass:
const helper = this.getHelper();

Methods

NssHelper.getAnimDuration(target, property_name, default_ms?)

Reads a CSS custom property containing a duration value and returns it as milliseconds.

Param	Type	Default	Description
target	HTMLElement	—	The element to read the CSS property from
property_name	string	—	The CSS custom property name (e.g. '--nss-modal-anim-dur')
default_ms	number	500	Fallback value in milliseconds if the property is not found

Returns number — the duration in milliseconds.

const duration = NssHelper.getAnimDuration(dialog_el, '--nss-confirm-anim-dur', 300);
// e.g. returns 500 if CSS has `--nss-confirm-anim-dur: 500ms`

---

NssHelper.isCfxBrowser()

Checks whether the current browser is the CitizenFX (FiveM/RedM) embedded browser.

Returns boolean — true if running inside the CFX NUI browser, false otherwise.

if (NssHelper.isCfxBrowser()) {
    nss_client.post('ready');
} else {
    console.log('Running in dev mode outside RedM');
}

---

NssHelper.getUniqueId()

Generates a unique string ID. Each call returns a new ID with an auto-incrementing counter.

Returns string — a unique ID in the format nss_helper_<n> (e.g. nss_helper_1, nss_helper_2).

const id = NssHelper.getUniqueId();
element.setAttribute('id', id);

---

NssHelper.debounceClocked(callback, interval_ms)

Creates a clocked debounce — fires the callback immediately on the first call, then ignores subsequent calls until the interval has passed. The last set of arguments is captured and used when the next execution fires.

Param	Type	Default	Description
callback	function	—	The function to debounce
interval_ms	number	—	The minimum interval between executions in milliseconds

Returns function — the debounced wrapper function.

const on_resize = NssHelper.debounceClocked(() => {
    recalculateLayout();
}, 100);

window.addEventListener('resize', on_resize);

---

NssHelper.debounce(callback, interval_ms)

Creates a standard trailing-edge debounce — resets the timer on each call and fires only after the interval has passed without further calls.

Param	Type	Default	Description
callback	function	—	The function to debounce
interval_ms	number	—	The delay in milliseconds

Returns function — the debounced wrapper function.

const on_input = NssHelper.debounce((value) => {
    nss_client.post('search', {query: value});
}, 300);

input_el.addEventListener('input', (e) => on_input(e.target.value));

---

NssHelper.setCircleClip(el, percentage)

Applies a circular clip-path: polygon() to an element, useful for circular progress indicators.

Param	Type	Default	Description
el	HTMLElement	—	The element to apply the clip-path to
percentage	number	—	A value between 0 (fully hidden) and 1 (fully visible)

Returns undefined

// Show 75% of a circular element
NssHelper.setCircleClip(progress_el, 0.75);

TIP

setCircleClip calculates polygon points for 12 segments. The percentage parameter maps to a clockwise fill starting from the top.

---

NssHelper.createObjectClone(obj, remove_nulls?)

Creates a deep clone of an object using structuredClone, optionally removing keys with null values.

Param	Type	Default	Description
obj	object	—	The object to clone
remove_nulls	boolean	false	If true, removes all keys where the value is null

Returns object — a deep clone of the input.

const data = {name: 'John', title: null, age: 30};
const clean = NssHelper.createObjectClone(data, true);
// Result: {name: 'John', age: 30}

---

NssHelper.getRandomArrayElement(array)

Picks a random element from an array.

Param	Type	Default	Description
array	Array	—	The source array

Returns * — a random element, or null if the array is empty.

const sounds = ['click_1.mp3', 'click_2.mp3', 'click_3.mp3'];
const random_sound = NssHelper.getRandomArrayElement(sounds);

Events / Callbacks

None. All methods are static utilities.

CSS

None. NssHelper has no visual representation.

Dependencies

None. NssHelper is a standalone utility with no external dependencies.

Things to Know

WARNING

All methods are static — never instantiate NssHelper with new.

• Access via responsive.getHelper() or this.getHelper() inside any NssUiComponent subclass.
• debounceClocked fires immediately then throttles; debounce waits until calls stop. Choose based on whether you need instant feedback (clocked) or final-value-only (standard).