What causes "Expected a DOM element" in quasarframework/quasar?

Wait until the element exists: call inside onMounted and use ref.value.

quasarframework/quasar · error · TypeError

Expected a DOM element

Error message

Expected a DOM element

What it means

getCssVar(propName, element) defaults element to document.body but accepts any Element; it throws this TypeError when the passed element is not an instanceof Element (null, undefined, strings, jQuery objects, or Vue refs). The function uses getComputedStyle(element), which requires a real DOM element.

Source

Thrown at ui/src/utils/css-var/get-css-var.js:6

export default function getCssVar(propName, element = document.body) {
  if (typeof propName !== 'string') {
    throw new TypeError('Expected a string as propName')
  }
  if (!(element instanceof Element)) {
    throw new TypeError('Expected a DOM element')
  }

  return (
    getComputedStyle(element).getPropertyValue(`--q-${propName}`).trim() || null
  )
}

View on GitHub (pinned to 4841521b5f)

Solutions

Wait until the element exists: call inside onMounted and use ref.value.
Pass a real DOM node: getCssVar('primary', document.querySelector('#app')).
Unwrap Vue refs: getCssVar('primary', elRef.value) after mount.
Omit the second argument to use the default document.body.

Example fix

// before
onBeforeSetup: const color = getCssVar('primary', elRef.value) // null, throws
// after
onMounted(() => {
  const color = getCssVar('primary', elRef.value)
})

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(element instanceof Element)) throw new Error('getCssVar requires a DOM element')

Type guard

const isDomElement = (el) => el instanceof Element

Try / catch

let value = null
try {
  value = getCssVar('primary', elRef.value)
} catch (err) {
  if (err instanceof TypeError && /DOM element/.test(err.message)) {
    value = getCssVar('primary') // fall back to document.body
  } else throw err
}

Prevention

Access template refs only inside onMounted (or later), not during setup/before mount.
Use document.querySelector() to convert selector strings into real elements.
Unwrap Vue refs (elRef.value) — the ref object itself is not an Element.
Omit the element argument when you actually want document.body.

When it happens

Trigger: getCssVar('primary', null); passing a template ref before mount (ref.value === null); passing document (a Document, not an Element); passing a selector string like '#app'; passing a jQuery/DOM wrapper object.

Common situations: Calling inside setup() before the component mounts so the ref is still null; SSR where document is undefined; passing window.document instead of document.body.

Related errors

AI-assisted analysis of quasarframework/quasar@4841521b5f (2026-08-30). Data as JSON: /api/errors/2ff6a550809d66b8. Report an issue: GitHub.