Dynamic Imports

Learning objectives#

• Load a module on demand with import()
• Read default and named exports from the result
• Use dynamic imports for code splitting
• Handle loading errors and show loading states

Explanation#

import("./chart.js") is a function-like expression that returns a promise for the module object. It can be used anywhere — inside if statements, event handlers or functions.

The resolved module has named exports as properties and the default export under .default: const { default: Chart, formatAxis } = await import("./chart.js").

Bundlers like Vite and webpack see import() and split that module (and its dependencies) into a separate file that is downloaded only when called.

Typical uses: heavy libraries (charts, PDF, editors), rarely used pages, admin areas, language files and polyfills for old browsers.

Top-level await (ES2022) lets a module wait for a dynamic import directly at the top level, without wrapping it in an async function.

Syntax#

1const module = await import('./heavy.js');
2module.default();      // default export
3module.namedThing();   // named export

Code example: Load a chart library only when clicked#

1const button = document.querySelector('#show-chart');
2const status = document.querySelector('#status');
3

4button.addEventListener('click', async () => {
5  status.textContent = 'Loading chart…';
6  try {
7    // chart.js and its dependencies are downloaded only now
8    const { default: renderChart, formatRupees } = await import('./chart.js');
9    renderChart('#sales', [120, 340, 210], { label: formatRupees });
10    status.textContent = '';
11  } catch (err) {
12    status.textContent = 'Could not load the chart. Check your connection.';
13    console.error(err);
14  }
15});
16

17// Load a translation file based on the user's language
18const lang = navigator.language.startsWith('hi') ? 'hi' : 'en';
19const { messages } = await import(`./i18n/${lang}.js`);   // top-level await
20document.title = messages.title;
21

22// React equivalent: const Reports = React.lazy(() => import('./Reports.jsx'));

The page loads without chart.js. Clicking the button shows “Loading chart…”, downloads chart.js, then draws the chart — or shows a friendly error if the download fails.

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. The click handler is async so it can await the import.
2. Destructuring pulls the default export (renamed renderChart) and a named export.
3. The bundler puts chart.js in its own file that is fetched on first click; later clicks reuse the cached module.
4. try/catch handles network failures with a helpful message.
5. A template literal chooses the language file at runtime.
6. React.lazy uses exactly the same import() under the hood.

Real-world use case#

Common mistakes#

Best practices#

• Split heavy, rarely used features
• Keep the critical first-page code in static imports
• Preload likely-needed chunks on hover or idle
• Always handle loading and error states

Remember this#

Practice exercise#

1async function openEditor() {
2  try {
3    const { default: createEditor } = await import('./editor.js');
4    createEditor('#editor');
5  } catch {
6    alert('The editor could not be loaded. Please try again.');
7  }
8}

Mini quiz#

Want more? Practise all ES6+ MCQs · ES6+ interview questions

Related topics#

My notes#

Saved in this browser.