Docs

JavaScript API

2 min readUpdated October 19, 2026

On pages where the phone field loads, the plugin adds window.NahnuSPF. Use it to add the flag dropdown to your own inputs, read numbers and check forms.

The script loads automatically on pages with the shortcodes, the checkout and account pages, and pages with a supported form. On other pages, call nahnu_spf_enqueue_assets() in PHP, or add your inputs with the nahnu_spf_selectors filter.

Wait for the API#

document.addEventListener('nahnu-spf:api-ready', (event) => {
  const api = event.detail; // same as window.NahnuSPF
});

Methods#

MethodWhat it does
NahnuSPF.attach(input, options)Adds the flag dropdown to an input (an element or a CSS selector) and returns the field. Returns the existing field if it already has one.
NahnuSPF.get(input)The field for an input that already has the dropdown, including the plugin’s own checkout fields.
NahnuSPF.getAll(form)All phone fields in a form or container.
NahnuSPF.scan(container)Sets up fields added to the page later. New fields are also found automatically.
NahnuSPF.validateAll(form)Checks every phone field in the form and shows the messages. Returns true when all are fine.
NahnuSPF.prepare(form)Puts the full international numbers in place, for forms sent by script.
NahnuSPF.detectCountry()A promise with the visitor’s country and state.

Options for attach()#

OptionWhat it does
countryTwo-letter starting country
detectUse location detection when no country or number is set
validate, validateOnBlur, validateOnSubmitNumber checking, when the field loses focus and when the form is sent
submitFullNumberSend the full international number (default on)
hiddenInputKeep the full number in a hidden input with the field’s name, for forms sent by script
onlyCountries, excludeCountries, preferredCountriesArrays of country codes, instead of the site settings
errorClass, inputErrorClass, errorScope, errorReplace, scopeErrorClassMessage styling, to match a form plugin
intlTelInputAny extra intl-tel-input options

Field methods#

getNumber(), getReadable(), getCountry(), getCountryName(), isValid(), getNumberType(), getError(), validate(), showError(message), clearError(), prepare(), setNumber(number), setCountry(iso2), destroy(), and a ready promise.

Events#

Fired on the input. They bubble, so you can listen on the form or document.

EventWhenDetail
nahnu-spf:readyA field is set upThe field
nahnu-spf:changeThe number or country changesnumber, country, valid, field
nahnu-spf:invalidA form is stopped by a wrong numberfield, message
nahnu-spf:api-readyThe API is loaded (fired on document)window.NahnuSPF

Example#

const phone = NahnuSPF.attach('#my_phone', { country: 'gb' });
phone.ready.then(() => console.log(phone.getNumber(), phone.isValid()));

document.querySelector('#my_form').addEventListener('submit', (e) => {
  if (!NahnuSPF.validateAll(e.target)) {
    e.preventDefault();
  }
});

Forms sent the normal way are handled automatically. Wrong numbers stop the form, and the full number is put in place before the form’s own submit handlers run.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only