framework7io/framework7 · error · Error

Framework7: can't create a View instance because ${typeof el

Error message

Framework7: can't create a View instance because ${typeof el === 'string' ? `the selector "${el}" didn't match any element` : 'el must be an HTMLElement or Dom7 object'}

What it means

A View (router container) requires a real DOM element. The View constructor throws when `el` is a CSS selector that matched nothing, or when `el` is neither an HTMLElement nor a Dom7 object. Framework7 cannot mount navigation into a missing container.

Source

Thrown at src/core/components/view/view-class.js:29

    const view = this;

    const ssr = view.params.routerId;

    const defaults = {
      routes: [],
      routesAdd: [],
    };

    if (!ssr) {
      const $el = $(el);
      if (!$el.length) {
        let message = "Framework7: can't create a View instance because ";
        message +=
          typeof el === 'string'
            ? `the selector "${el}" didn't match any element`
            : 'el must be an HTMLElement or Dom7 object';

        throw new Error(message);
      }
    }

    // Default View params
    view.params = extend({ el }, defaults, app.params.view, viewParams);

    // Routes
    if (view.params.routes.length > 0) {
      view.routes = view.params.routes;
    } else {
      view.routes = [].concat(app.routes, view.params.routesAdd);
    }

    // View Props
    extend(false, view, {
      app,
      name: view.params.name,
      main: view.params.main,

View on GitHub (pinned to 6557591266)

Solutions

Ensure the element exists in the DOM before creating the View (wrap init in DOMContentLoaded or run after render)
Verify the selector string for typos and that the id/class matches exactly
Pass an HTMLElement (`document.querySelector('.view')`) or a Dom7 object (`$$('.view')`) instead of other wrappers
If the element is conditionally rendered, create the View after it is mounted

Example fix

// before
const mainView = app.views.create('#main-view'); // element not yet in DOM

// after
document.addEventListener('DOMContentLoaded', () => {
  const el = document.querySelector('#main-view');
  if (el) app.views.create(el);
});

Defensive patterns

Strategy: validation

Validate before calling

const el = typeof selector === 'string' ? document.querySelector(selector) : selector;
if (!el) throw new Error(`View element not found: ${selector}`);
const view = app.views.create(el, viewParams);

Type guard

function isDomTarget(el) {
  return el instanceof HTMLElement || (el && Array.isArray(el) && el[0] instanceof HTMLElement);
}

Try / catch

try {
  const view = app.views.create('#main-view');
} catch (e) {
  if (/didn't match any element|must be an HTMLElement/.test(e.message)) {
    console.error('View target element missing; check selector and DOM timing');
  } else throw e;
}

Prevention

Initialize Views after DOMContentLoaded or after framework render
Log document.querySelector(selector) before creating to confirm it exists
Prefer passing the HTMLElement or Dom7 object over raw selectors
Keep selectors in one constants module to avoid typos

When it happens

Trigger: `app.views.create('#my-view')` where no element with that selector exists at call time; passing null/undefined or a jQuery object instead of Dom7/HTMLElement; creating the View before the DOM is rendered.

Common situations: Script executing before DOMContentLoaded; selector typo or renamed id; Views initialized in a page fragment not yet attached; migrating from jQuery where `$('#el')[0]` is needed.

Related errors

AI-assisted analysis of framework7io/framework7@6557591266 (2026-09-02). Data as JSON: /api/errors/037d4d7b6a3244d9. Report an issue: GitHub.