Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Classes and Modules

Dynamic import()

Reference for JavaScript dynamic import(): load modules on demand, get a promise for the module namespace, handle failures, and use it in classic scripts.

import() loads an ES module at run time and returns a promise for its module namespace object. Unlike a static import declaration, it can appear anywhere an expression is allowed: inside a function, behind an if, or in an event handler. That makes it the tool for code splitting, lazy loading and choosing a module based on a value you only know at run time.

Despite its call-like look, import() is syntax, not a function. You cannot store it in a variable, call it with .call(), or spread arguments into it.

JavaScript
const module = await import("./chart.js");
module.draw(data);

Try it

JS Load a module on demand

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Failures reject the promise

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
import(specifier)
import(specifier, options)
Name Description
specifier Any expression that evaluates to a string (it is converted to a string). A relative path, an absolute URL, or a bare name that an import map or bundler can resolve. Relative paths resolve against the file that contains the import(), not against the page.
options Optional object. The with property carries import attributes, for example { with: { type: "json" } } for a JSON module.

Return value: a promise that fulfills with the module namespace object. Named exports become properties, and the default export is the property default.

Exceptions: the promise rejects if the specifier cannot be resolved or fetched, if the module has a syntax error, or if the module throws while it runs. A non-string-convertible specifier also rejects rather than throwing synchronously.

Usage notes

  • Works everywhere. import() is allowed in classic scripts as well as modules, which is the usual way to start using modules from old code.
  • Evaluated once. The same specifier returns the same module instance. The module body runs the first time only; later calls resolve with the cached namespace.
  • Namespace objects are read-only. You can read exports and destructure them, but you cannot add, change or delete properties.
  • Default exports are under default. const { default: Widget } = await import("./widget.js") is the destructuring form.
  • Handle failure. Network errors and bad paths reject the promise. Wrap the call in try/catch or add .catch(), and consider showing a retry option.
  • Not a function. There is no import.call(), and import on its own is not a value. Wrap it in your own function when you need to pass it around.
  • Bundlers. Build tools turn import("./x.js") into a separate chunk. Keep the specifier as a plain string, or a simple template with a fixed folder prefix, so the tool can see which files to include.
  • Top-level await. In a module you can write await import(...) directly, without an async function.
  • Use sparingly. Loading on demand saves startup cost but adds a network round trip later. Preload or prefetch likely modules if the delay would be noticeable.

Browser support

Supported in all current browsers, in classic scripts and modules. Import attributes (the with option) are newer, so check a compatibility table before relying on them.