The import
statement is used to import bindings which are exported by another module.
This feature is only just beginning to be implemented in browsers natively at this time. It is implemented in many transpilers, such as TypeScript and Babel, and bundlers such as Rollup and Webpack.
Syntax
import defaultExport from "module-name"; import * as name from "module-name"; import { export } from "module-name"; import { export as alias } from "module-name"; import { export1 , export2 } from "module-name"; import { export1 , export2 as alias2 , [...] } from "module-name"; import defaultExport, { export [ , [...] ] } from "module-name"; import defaultExport, * as name from "module-name"; 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, excluding the.js
extension. Certain bundlers may permit or require the use of the extension; check your environment. Only single quotes and double quotes Strings are allowed. name
- Name of the module object that will be used as a kind of namespace when referring to the imports.
export, exportN
- Name of the exports to be imported.
alias, 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
Examples
Importing 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); });
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Imports' in that specification. |
Standard | Initial definition. |
ECMAScript Latest Draft (ECMA-262) The definition of 'Imports' in that specification. |
Living Standard |
Browser compatibility
Feature | Chrome | Edge | Firefox | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | 61 | 16 151 | 542 | No | 47 | 10.1 |
Feature | Android webview | Chrome for Android | Edge mobile | Firefox for Android | IE mobile | Opera Android | iOS Safari |
---|---|---|---|---|---|---|---|
Basic support | No | 61 | Yes | 542 | No | 47 | 10.1 |
1. From version 15: this feature is behind the Experimental JavaScript Features
preference.
2. From version 54: this feature is behind the dom.moduleScripts.enabled
preference. To change preferences in Firefox, visit about:config.
See also
export
- Previewing ES6 Modules and more from ES2015, ES2016 and beyond
- ES6 in Depth: Modules, Hacks blog post by Jason Orendorff
- Axel Rauschmayer's book: "Exploring JS: Modules"