The static import
statement is used to import bindings which are exported by another module. Imported modules are in strict mode
whether you declare them as such or not. The import
statement cannot be used in embedded scripts unless such script has a type="module"
.
There is also a function-like dynamic import()
, which does not require scripts of type="module"
.
Backward compatibility can be ensured using attribute nomodule
on the script tag.
Dynamic import is useful in situations where you wish to load a module conditionally, or on-demand. The static form is preferable for loading initial dependencies, and can benefit more readily from static analysis tools and tree shaking.
Syntax
import defaultExport from "module-name"; import * as name from "module-name"; import { export1 } from "module-name"; import { export1 as alias1 } from "module-name"; import { export1 , export2 } from "module-name"; import { foo , bar } from "module-name/path/to/specific/un-exported/file"; import { export1 , export2 as alias2 , [...] } from "module-name"; import defaultExport, { export1 [ , [...] ] } from "module-name"; import defaultExport, * as name from "module-name"; import "module-name"; var promise = import("module-name");
defaultExport
- Name that will refer to the default export from the module.
module-name
- The module to import from. This is often a relative or absolute path name to the
.js
file containing the module. Certain bundlers may permit or require the use of the extension; check your environment. Only single quoted and double quoted Strings are allowed. name
- Name of the module object that will be used as a kind of namespace when referring to the imports.
exportN
- Name of the exports to be imported.
aliasN
- Names that will refer to the named imports.
Description
The name
parameter is the name of the "module object" which will be used as a kind of namespace to refer to the exports. The export
parameters specify individual named exports, while the import * as name
syntax imports all of them. Below are examples to clarify the syntax.
Import an entire module's contents
This inserts myModule
into the current scope, containing all the exports from the module in the file located in /modules/my-module.js
.
import * as myModule from '/modules/my-module.js';
Here, accessing the exports means using the module name ("myModule" in this case) as a namespace. For example, if the module imported above includes an export doAllTheAmazingThings()
, you would call it like this:
myModule.doAllTheAmazingThings();
Import a single export from a module
Given an object or value named myExport
which has been exported from the module my-module
either implicitly (because the entire module is exported) or explicitly (using the export
statement), this inserts myExport
into the current scope.
import {myExport} from '/modules/my-module.js';
Import multiple exports from module
This inserts both foo
and bar
into the current scope.
import {foo, bar} from '/modules/my-module.js';
Import an export with a more convenient alias
You can rename an export when importing it. For example, this inserts shortName
into the current scope.
import {reallyReallyLongModuleExportName as shortName} from '/modules/my-module.js';
Rename multiple exports during import
Import multiple exports from a module with convenient aliases.
import { reallyReallyLongModuleExportName as shortName, anotherLongModuleName as short } from '/modules/my-module.js';
Import a module for its side effects only
Import an entire module for side effects only, without importing anything. This runs the module's global code, but doesn't actually import any values.
import '/modules/my-module.js';
Importing defaults
It is possible to have a default export
(whether it is an object, a function, a class, etc.). The import
statement may then be used to import such defaults.
The simplest version directly imports the default:
import myDefault from '/modules/my-module.js';
It is also possible to use the default syntax with the ones seen above (namespace imports or named imports). In such cases, the default import will have to be declared first. For instance:
import myDefault, * as myModule from '/modules/my-module.js'; // myModule used as a namespace
or
import myDefault, {foo, bar} from '/modules/my-module.js'; // specific, named imports
Dynamic Imports
The import
keyword may be called as a function to dynamically import a module. When used this way, it returns a promise.
import('/modules/my-module.js') .then((module) => { // Do something with the module. });
This form also supports the await keyword.
let module = await import('/modules/my-module.js');
Examples
Standard Import
The code below shows how to import from a secondary module to assist in processing an AJAX JSON request.
The module: file.js
function getJSON(url, callback) { let xhr = new XMLHttpRequest(); xhr.onload = function () { callback(this.responseText) }; xhr.open('GET', url, true); xhr.send(); } export function getUsefulContents(url, callback) { getJSON(url, data => callback(JSON.parse(data))); }
The main program: main.js
import { getUsefulContents } from '/modules/file.js'; getUsefulContents('http://www.example.com', data => { doSomethingUseful(data); });
Dynamic Import
This example shows how to load functionality on to a page based on a user action, in this case a button click, and then call a function within that module. This is not the only way to implement this functionality. The import()
function also supports await
.
const main = document.querySelector("main"); for (const link of document.querySelectorAll("nav > a")) { link.addEventListener("click", e => { e.preventDefault(); import('/modules/my-module.js') .then(module => { module.loadPageInto(main); }) .catch(err => { main.textContent = err.message; }); }); }
Specifications
Specification | Status | Comment |
---|---|---|
"function-like" dynamic import() proposal |
Stage 4 | Due to be standardized in ECMAScript 2020 |
ECMAScript Latest Draft (ECMA-262) The definition of 'Imports' in that specification. |
Draft | |
ECMAScript 2018 (ECMA-262) The definition of 'Imports' in that specification. |
Standard | |
ECMAScript 2017 (ECMA-262) The definition of 'Imports' in that specification. |
Standard | |
ECMAScript 2016 (ECMA-262) The definition of 'Imports' in that specification. |
Standard | |
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Imports' in that specification. |
Standard | Initial definition. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
import | Chrome Full support 61 | Edge
Full support
16
| Firefox
Full support
60
| IE No support No | Opera Full support 47 | Safari Full support 10.1 | WebView Android Full support 61 | Chrome Android Full support 61 | Firefox Android
Full support
60
| Opera Android Full support 44 | Safari iOS Full support 10.3 | Samsung Internet Android Full support 8.0 | nodejs
Full support
8.5.0
|
Dynamic import | Chrome Full support 63 | Edge
No support
No
| Firefox
Full support
67
| IE No support No | Opera Full support 50 | Safari Full support 11.1 | WebView Android Full support 63 | Chrome Android Full support 63 | Firefox Android
Full support
67
| Opera Android Full support 46 | Safari iOS Full support 11.3 | Samsung Internet Android Full support 8.0 | nodejs ? |
Available in workers | Chrome
Full support
80
| Edge No support No | Firefox No support No | IE No support No | Opera No support No | Safari No support No | WebView Android Full support 80 | Chrome Android
Full support
80
| Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android No support No | nodejs
Full support
Yes
|
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- See implementation notes.
- See implementation notes.
- User must explicitly enable this feature.
- User must explicitly enable this feature.
Implementation Progress
The following table provides a daily implementation status for this feature, because this feature has not yet reached cross-browser stability. The data is generated by running the relevant feature tests in Test262, the standard test suite of JavaScript, in the nightly build, or latest release of each browser's JavaScript engine.
See also
export
import.meta
- Limin Zhu, Brian Terlson and Microsoft Edge Team: Previewing ES6 Modules and more from ES2015, ES2016 and beyond
- Hacks blog post by Jason Orendorff: ES6 in Depth: Modules
- Hacks blog post by Lin Clark: ES modules: A cartoon deep-dive
- Axel Rauschmayer's book: "Exploring JS: Modules"
- The Modern JavaScript Tutorial(javascript.info): Export and Import