sindresorhus/is · error · TypeError

Expected value which is `HTMLElement`, received value of typ

Error message

Expected value which is `HTMLElement`, received value of type `${is(value)}`.

What it means

Thrown by `assertHtmlElement()` when `isHtmlElement()` fails — the value is not an HTMLElement instance. This guards DOM-manipulating code against receiving selectors, nulls, or non-HTML nodes.

Source

Thrown at source/index.ts:1659

		throw new TypeError(message ?? typeErrorMessage('Function', value));
	}
}

export function assertGenerator(value: unknown, message?: string): asserts value is Generator {
	if (!isGenerator(value)) {
		throw new TypeError(message ?? typeErrorMessage('Generator', value));
	}
}

export function assertGeneratorFunction(value: unknown, message?: string): asserts value is GeneratorFunction {
	if (!isGeneratorFunction(value)) {
		throw new TypeError(message ?? typeErrorMessage('GeneratorFunction', value));
	}
}

export function assertHtmlElement(value: unknown, message?: string): asserts value is HTMLElement {
	if (!isHtmlElement(value)) {
		throw new TypeError(message ?? typeErrorMessage('HTMLElement', value));
	}
}

export function assertInfinite(value: unknown, message?: string): asserts value is number {
	if (!isInfinite(value)) {
		throw new TypeError(message ?? typeErrorMessage('infinite number', value));
	}
}

export function assertInRange(value: number, range: number | [number, number], message?: string): asserts value is number {
	if (!isInRange(value, range)) {
		throw new TypeError(message ?? typeErrorMessage('in range', value));
	}
}

export function assertInt16Array(value: unknown, message?: string): asserts value is Int16Array {
	if (!isInt16Array(value)) {
		throw new TypeError(message ?? typeErrorMessage('Int16Array', value));

View on GitHub ↗ (pinned to 7821031c66)

Solutions

Handle the null case: check the querySelector result exists before asserting, or fix the selector/timing (run after DOMContentLoaded).
Unwrap wrappers: pass `$(el)[0]` or `ref.current`, not the wrapper object.
If SVG elements are valid inputs, broaden the check to `is.element` (Element) instead of `is.htmlElement`.
Guard against SSR: only run the assertion in browser code paths.

Example fix

// before
const el = document.querySelector('#app');
assertHtmlElement(el); // throws if not found → null
// after
const el = document.querySelector('#app');
if (el === null) throw new Error('#app not found in DOM');
assertHtmlElement(el);

Defensive patterns

Strategy: validation

Validate before calling

if (typeof HTMLElement === 'undefined') {
  throw new Error('HTMLElement check requires a DOM environment');
}
if (!(value instanceof HTMLElement)) {
  throw new TypeError('Expected an HTMLElement');
}

Type guard

function isHTMLElement(value: unknown): value is HTMLElement {
  return typeof HTMLElement !== 'undefined' && value instanceof HTMLElement;
}

Try / catch

try {
  assert.htmlElement(el);
} catch (error) {
  if (error instanceof TypeError) { /* selector missed or ran outside DOM; handle missing element */ }
  else throw error;
}

Prevention

`document.querySelector` returns null when nothing matches — null-check before asserting
Text nodes, comments, SVG elements, and document itself are not HTMLElements; check nodeType/interface accordingly
In Node/SSR or jsdom-less tests there is no DOM — gate the code path on environment, and remember cross-iframe elements fail instanceof against the parent realm's HTMLElement

When it happens

Trigger: `is.assert.htmlElement(value)` with `null` from `document.querySelector()` finding nothing, a CSS selector string, a jQuery-like wrapper, a text/comment node, an SVGElement, or any value in a non-DOM environment (Node, jsdom edge cases, SSR).

Common situations: Running DOM code during server-side rendering or in Node tests without jsdom; querying for an element before the DOM is ready so the selector returns null; SVG elements failing because they are SVGElement, not HTMLElement; elements from a detached iframe/realm depending on how the check is implemented.

Related errors

AI-assisted analysis of sindresorhus/is@7821031c66 (2026-07-31). Data as JSON: /data/errors/0c72a4629340f316.json. Report an issue: GitHub ↗.