What causes "[cleave.js] Please check the element" in nosir/cleave.js?

Ensure the element exists before constructing: wrap in DOMContentLoaded or place the script before .

nosir/cleave.js · error · Error

[cleave.js] Please check the element

Error message

[cleave.js] Please check the element

What it means

Cleave throws this when it cannot resolve a valid DOM element to attach formatting to. The constructor checks `owner.element` after resolving a string selector or raw element, and if it is null/undefined the instance is useless, so it fails fast at src/Cleave.js:26.

Source

Thrown at src/Cleave.js:26

 */
var Cleave = function (element, opts) {
    var owner = this;
    var hasMultipleElements = false;

    if (typeof element === 'string') {
        owner.element = document.querySelector(element);
        hasMultipleElements = document.querySelectorAll(element).length > 1;
    } else {
      if (typeof element.length !== 'undefined' && element.length > 0) {
        owner.element = element[0];
        hasMultipleElements = element.length > 1;
      } else {
        owner.element = element;
      }
    }

    if (!owner.element) {
        throw new Error('[cleave.js] Please check the element');
    }

    if (hasMultipleElements) {
      try {
        // eslint-disable-next-line
        console.warn('[cleave.js] Multiple input fields matched, cleave.js will only take the first one.');
      } catch (e) {
        // Old IE
      }
    }

    opts.initValue = owner.element.value;

    owner.properties = Cleave.DefaultProperties.assign({}, opts);

    owner.init();
};

View on GitHub (pinned to a966c95cf5)

Solutions

Ensure the element exists before constructing: wrap in DOMContentLoaded or place the script before </body>.
Verify the selector string matches exactly one input element (check for typos).
Pass the actual HTMLElement, not a jQuery object or NodeList.
When the element may be absent, guard before constructing.

Example fix

// before
new Cleave('.phone-input', { phone: true, phoneRegionCode: 'US' });
// after
const el = document.querySelector('.phone-input');
if (el) {
  new Cleave(el, { phone: true, phoneRegionCode: 'US' });
}

Defensive patterns

Strategy: validation

Validate before calling

function canInitCleave(target) {
  const el = typeof target === 'string' ? document.querySelector(target) : target;
  return !!(el && el.tagName === 'INPUT');
}
if (!canInitCleave('.phone-input')) throw new Error('Cleave target element not found');

Type guard

function isCleaveTarget(el) {
  return el instanceof HTMLElement && el.tagName === 'INPUT' && typeof el.value === 'string';
}

Try / catch

try {
  new Cleave(selector, opts);
} catch (e) {
  if (e.message.includes('Please check the element')) {
    console.warn('Cleave: target not found for', selector);
  } else { throw e; }
}

Prevention

Initialize Cleave after DOM ready (DOMContentLoaded or useEffect/componentDidMount).
Pre-resolve the element with querySelector and assert it before constructing.
Use unique selectors (ids) rather than broad class selectors.
In frameworks, attach Cleave in a mount lifecycle/ref callback, not at module load.

When it happens

Trigger: new Cleave(null); new Cleave('input.phone') where the selector matches nothing; passing a jQuery-wrapped set or an array-like that has no .value; calling new Cleave() before the DOM is rendered (script runs before the input exists).

Common situations: Script loaded in <head> without DOMContentLoaded; typo in the CSS selector; React/Vue component rendering after the Cleave constructor runs; passing the wrong variable (undefined) from an optional ref.

Related errors

AI-assisted analysis of nosir/cleave.js@a966c95cf5 (2026-09-02). Data as JSON: /api/errors/8b16b9f3cce6e560. Report an issue: GitHub.