CINXE.COM

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="x-ua-compatible" content="ie=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><script>!function(e,t,a,n){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var g=t.getElementsByTagName(a)[0],m=t.createElement(a);m.async=!0,m.src="https://www.googletagmanager.com/gtm.js?id=GTM-5VSZM5J",g.parentNode.insertBefore(m,g)}(window,document,"script","dataLayer")</script><meta name="description" content="How to migrate web interop code from dart:html to package:web."><title>Migrate to package:web | Dart</title><link rel="icon" sizes="64x64" href="/assets/img/logo/dart-64.png" eleventy:ignore><link href="/assets/img/touch-icon-iphone.png" rel="apple-touch-icon" eleventy:ignore><link href="/assets/img/touch-icon-ipad.png" rel="apple-touch-icon" sizes="152x152" eleventy:ignore><link href="/assets/img/touch-icon-iphone-retina.png" rel="apple-touch-icon" sizes="180x180" eleventy:ignore><link href="/assets/img/touch-icon-ipad-retina.png" rel="apple-touch-icon" sizes="167x167" eleventy:ignore><meta name="twitter:card" content="summary"><meta name="twitter:site" content="@dart_lang"><meta name="twitter:title" content="Migrate to package:web"><meta name="twitter:description" content="How to migrate web interop code from dart:html to package:web."><meta property="og:title" content="Migrate to package:web"><meta property="og:description" content="How to migrate web interop code from dart:html to package:web."><meta property="og:url" content="/interop/js-interop/package-web/"><meta property="og:image" content="/assets/img/logo/dart-logo-for-shares.png?2" eleventy:ignore><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Display:wght@400&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0..1,0" rel="stylesheet"><link rel="stylesheet" href="/assets/css/main.css?v=2"><script src="/assets/js/os-tabs.js?v=2"></script><script src="/assets/js/main.js?v=2"></script><script>!function(e,a,t,n,c,o,s){e.GoogleAnalyticsObject=c,e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},e[c].l=1*new Date,o=a.createElement(t),s=a.getElementsByTagName(t)[0],o.async=1,o.src="//www.google-analytics.com/analytics.js",s.parentNode.insertBefore(o,s)}(window,document,"script",0,"ga"),ga("create","UA-26406144-4","auto"),ga("send","pageview")</script></head><body class="default.html"><a id="skip" href="#site-content-title" tabindex="1">Skip to main content</a><section id="cookie-notice"><div class="container"><p>dart.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic.</p><div class="button-group"><a class="text-button" href="https://policies.google.com/technologies/cookies" target="_blank" rel="noopener">Learn more</a> <button id="cookie-consent" class="filled-button">OK, got it</button></div></div></section><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5VSZM5J" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><div id="site-banner" role="alert"><p>Announcing Dart 3.7! Find out about updates to the language, analyzer, pub.dev, and more, in the <a href="https://medium.com/dartlang/announcing-dart-3-7-bf864a1b195c" target="_blank">blog post</a>.</p></div><header id="page-header" class="site-header"><nav id="mainnav" class="site-header"><div id="menu-toggle"><span class="material-symbols" title="Toggle side navigation menu." aria-label="Toggle side navigation menu." type="button">menu</span></div><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart"></a><ul class="navbar"><li><a href="/overview" class="nav-link">Overview</a></li><li class="mainnav__get-started"><a href="/docs" class="nav-link"><span>Docs</span></a></li><li><a href="/community" class="nav-link">Community</a></li><li><a href="/#try-dart" class="nav-link">Try Dart</a></li><li><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="searchfield"><form action="/search" class="site-header__search form-inline" id="cse-search-box"><input type="hidden" name="cx" value="011220921317074318178:_yy-tmb5t_i"> <input type="hidden" name="ie" value="UTF-8"> <input type="hidden" name="hl" value="en"> <input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-main" autocomplete="off" placeholder="Search" aria-label="Search"></form></li></ul></nav></header><div id="site-below-header"><div id="site-main-row"><div id="sidenav"><form action="/search/" class="site-header__search form-inline"><input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-side" autocomplete="off" placeholder="Search" aria-label="Search"></form><ul class="navbar-nav"><li aria-hidden="true"><div class="sidenav-divider"></div></li><li class="nav-item"><a href="/overview" class="nav-link">Overview</a></li><li class="nav-item"><a href="/community" class="nav-link">Community</a></li><li class="nav-item"><a href="https://dartpad.dev" class="nav-link">Try Dart</a></li><li class="nav-item"><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="nav-item"><a href="/docs" class="nav-link">Docs</a></li><li aria-hidden="true"><div class="sidenav-divider"></div></li></ul><ul class="nav"><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-1" role="button" aria-expanded="false" aria-controls="-sidenav-1"><span>Language</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1"><li class="nav-item"><a class="nav-link" href="/language"><div><span>Introduction</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-2" role="button" aria-expanded="false" aria-controls="-sidenav-1-2"><span>Syntax basics</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables"><div><span>Variables</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/operators"><div><span>Operators</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/comments"><div><span>Comments</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/metadata"><div><span>Metadata</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/libraries"><div><span>Libraries & imports</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/keywords"><div><span>Keywords</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-3" role="button" aria-expanded="false" aria-controls="-sidenav-1-3"><span>Types</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types"><div><span>Built-in types</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/records"><div><span>Records</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/collections"><div><span>Collections</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/generics"><div><span>Generics</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs"><div><span>Typedefs</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/type-system"><div><span>Type system</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-4" role="button" aria-expanded="false" aria-controls="-sidenav-1-4"><span>Patterns</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns"><div><span>Overview & usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types"><div><span>Pattern types</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://codelabs.developers.google.com/codelabs/dart-patterns-records" target="_blank" rel="noopener"><div><span>Applied tutorial</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions"><div><span>Functions</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-6" role="button" aria-expanded="false" aria-controls="-sidenav-1-6"><span>Control flow</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops"><div><span>Loops</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/branches"><div><span>Branches</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling"><div><span>Error handling</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-7" role="button" aria-expanded="false" aria-controls="-sidenav-1-7"><span>Classes & objects</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes"><div><span>Classes</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/constructors"><div><span>Constructors</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/methods"><div><span>Methods</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/extend"><div><span>Extend a class</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/mixins"><div><span>Mixins</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/enums"><div><span>Enums</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods"><div><span>Extension methods</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types"><div><span>Extension types</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects"><div><span>Callable objects</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-8" role="button" aria-expanded="false" aria-controls="-sidenav-1-8"><span>Class modifiers</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers"><div><span>Overview & usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/class-modifiers-for-apis"><div><span>Class modifiers for API maintainers</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference"><div><span>Reference</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-9" role="button" aria-expanded="false" aria-controls="-sidenav-1-9"><span>Concurrency</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/async"><div><span>Asynchronous support</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/isolates"><div><span>Isolates</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-10" role="button" aria-expanded="false" aria-controls="-sidenav-1-10"><span>Null safety</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety"><div><span>Sound null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide"><div><span>Migrating to null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/understanding-null-safety"><div><span>Understanding null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety"><div><span>Unsound null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq"><div><span>FAQ</span></div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-2" role="button" aria-expanded="false" aria-controls="-sidenav-2"><span>Core libraries</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core"><div><span>dart:core</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async"><div><span>dart:async</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math"><div><span>dart:math</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert"><div><span>dart:convert</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io"><div><span>dart:io</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop"><div><span>dart:js_interop</span></div></a></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables"><div><span>Iterable collections</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-2-10" role="button" aria-expanded="false" aria-controls="-sidenav-2-10"><span>Asynchronous programming</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await"><div><span>Tutorial</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling"><div><span>Futures and error handling</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams"><div><span>Using streams</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams"><div><span>Creating streams</span></div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-3" role="button" aria-expanded="false" aria-controls="-sidenav-3"><span>Effective Dart</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-3"><li class="nav-item"><a class="nav-link" href="/effective-dart"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style"><div><span>Style</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/documentation"><div><span>Documentation</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/usage"><div><span>Usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design"><div><span>Design</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-4" role="button" aria-expanded="false" aria-controls="-sidenav-4"><span>Packages</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages"><div><span>How to use packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages"><div><span>Commonly used packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/create-packages"><div><span>Creating packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing"><div><span>Publishing packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages"><div><span>Writing package pages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/workspaces"><div><span>Workspaces (monorepo support)</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-4-7" role="button" aria-expanded="false" aria-controls="-sidenav-4-7"><span>Package reference</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-4-7"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies"><div><span>Dependencies</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary"><div><span>Glossary</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/package-layout"><div><span>Package layout conventions</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables"><div><span>Pub environment variables</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec"><div><span>Pubspec file</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot"><div><span>Troubleshooting pub</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers"><div><span>Verified publishers</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories"><div><span>Security advisories</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning"><div><span>Versioning</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories"><div><span>Custom package repositories</span></div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/tools/pub/private-files"><div><span>What not to commit</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-5" role="button" aria-expanded="false" aria-controls="-sidenav-5"><span>Development</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-5"><li class="nav-item"><a class="nav-link" href="/libraries/serialization/json"><div><span>JSON serialization</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/number-representation"><div><span>Number representation</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis"><div><span>Google APIs</span></div></a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps"><div><span>Multi-platform apps</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-5-5" role="button" aria-expanded="false" aria-controls="-sidenav-5-5"><span>Command-line & server apps</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started"><div><span>Get started</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/cmdline"><div><span>Write command-line apps</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data"><div><span>Fetch data from the internet</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver"><div><span>Write HTTP servers</span></div></a></li><li class="nav-item"><a class="nav-link" href="/server/libraries"><div><span>Libraries & packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud"><div><span>Google Cloud</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-5-6" role="button" aria-expanded="false" aria-controls="-sidenav-5-6"><span>Web apps</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/get-started"><div><span>Get started</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/deployment"><div><span>Deployment</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/libraries"><div><span>Libraries & packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/wasm"><div><span>Wasm compilation</span></div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/libraries/core/environment-declarations"><div><span>Environment declarations</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link active collapsible" data-toggle="collapse" data-target="#-sidenav-6" role="button" aria-expanded="true" aria-controls="-sidenav-6"><span>Interoperability</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop"><div><span>C interop</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop"><div><span>Objective-C & Swift interop</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop"><div><span>Java & Kotlin interop</span></div></a></li><li class="nav-item"><button class="nav-link active collapsible" data-toggle="collapse" data-target="#-sidenav-6-4" role="button" aria-expanded="true" aria-controls="-sidenav-6-4"><span>JavaScript interop</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage"><div><span>Usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types"><div><span>JS types</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials"><div><span>Tutorials</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop"><div><span>Past JS interop</span></div></a></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link active" href="/interop/js-interop/package-web"><div><span>Web interop</span></div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-7" role="button" aria-expanded="false" aria-controls="-sidenav-7"><span>Tools & techniques</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools"><div><span>Overview</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-2" role="button" aria-expanded="false" aria-controls="-sidenav-7-2"><span>Editors & debuggers</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin"><div><span>IntelliJ & Android Studio</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code"><div><span>VS Code</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools"><div><span>Dart DevTools</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-2-4" role="button" aria-expanded="false" aria-controls="-sidenav-7-2-4"><span>DartPad</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot"><div><span>Troubleshooting DartPad</span></div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-3" role="button" aria-expanded="false" aria-controls="-sidenav-7-3"><span>Command-line tools</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-3"><li class="nav-item"><button class="nav-link collapsible" data-toggle="collapse" data-target="#-sidenav-7-3-1" role="button" aria-expanded="true" aria-controls="-sidenav-7-3-1"><span>Dart SDK</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool"><div><span>dart</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze"><div><span>dart analyze</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile"><div><span>dart compile</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create"><div><span>dart create</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc"><div><span>dart doc</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix"><div><span>dart fix</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format"><div><span>dart format</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info"><div><span>dart info</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd"><div><span>dart pub</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run"><div><span>dart run</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test"><div><span>dart test</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime"><div><span>dartaotruntime</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags"><div><span>Experiment flags</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible" data-toggle="collapse" data-target="#-sidenav-7-3-2" role="button" aria-expanded="true" aria-controls="-sidenav-7-3-2"><span>Other command-line tools</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner"><div><span>build_runner</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev"><div><span>webdev</span></div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-4" role="button" aria-expanded="false" aria-controls="-sidenav-7-4"><span>Static analysis</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis"><div><span>Customizing static analysis</span></div></a></li><li class="nav-item"><a class="nav-link" href="/deprecated/sound-problems"><div><span>Fixing common type problems</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons"><div><span>Fixing type promotion failures</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules"><div><span>Linter rules</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages"><div><span>Diagnostic messages</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-5" role="button" aria-expanded="false" aria-controls="-sidenav-7-5"><span>Testing & optimization</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/tools/testing"><div><span>Testing</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/debugging"><div><span>Debugging web apps</span></div></a></li></ul></li></ul></li><li aria-hidden="true"><div class="sidenav-divider"></div></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-9" role="button" aria-expanded="false" aria-controls="-sidenav-9"><span>Resources</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet"><div><span>Language cheatsheet</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes"><div><span>Breaking changes</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/evolution"><div><span>Language evolution</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/spec"><div><span>Language specification</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration"><div><span>Dart 3 migration guide</span></div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-9-6" role="button" aria-expanded="false" aria-controls="-sidenav-9-6"><span>Coming from ...</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-9-6"><li class="nav-item"><a class="nav-link" href="/resources/coming-from/js-to-dart"><div><span>JavaScript to Dart</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart"><div><span>Swift to Dart</span></div></a></li></ul></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq"><div><span>FAQ</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary"><div><span>Glossary</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/books"><div><span>Books</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/videos"><div><span>Videos</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials"><div><span>Tutorials</span></div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible" data-toggle="collapse" data-target="#-sidenav-10" role="button" aria-expanded="true" aria-controls="-sidenav-10"><span>Related sites</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-10"><li class="nav-item"><a class="nav-link" href="https://api.dart.dev" target="_blank" rel="noopener"><div><span>API reference</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener"><div><span>Blog</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener"><div><span>DartPad (online editor)</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener"><div><span>Flutter</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener"><div><span>Package site</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li></ul></li></ul></div><main id="page-content"><div id="site-toc--side" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry nav-item"><a class="nav-link" href="#package-web-vs-dart-html">package:web vs dart:html</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#migrating-from-dart-html">Migrating from dart:html</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#renames">Renames</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#type-tests">Type tests</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#type-signatures">Type signatures</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#conditional-imports">Conditional imports</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#virtual-dispatch-and-mocking">Virtual dispatch and mocking</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#non-native-apis">Non-native APIs</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#zones">Zones</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#helpers">Helpers</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#examples">Examples</a></li></ul></div><article><div class="content"><div id="site-content-title"><h1>Migrate to package:web</h1></div><div id="site-toc--inline" class="site-toc toc-collapsible toc-collapsed"><header class="site-toc__title">Contents <span class="site-toc--inline__toggle toc-toggle-down"><i class="material-symbols">keyboard_arrow_down</i></span> <span class="site-toc--inline__toggle toc-toggle-up"><i class="material-symbols">keyboard_arrow_up</i></span></header><ul class="section-nav"><li class="toc-entry"><a href="#package-web-vs-dart-html">package:web vs dart:html</a></li><li class="toc-entry"><a href="#migrating-from-dart-html">Migrating from dart:html</a><ul><li class="toc-entry"><a href="#renames">Renames</a></li><li class="toc-entry"><a href="#type-tests">Type tests</a></li><li class="toc-entry"><a href="#type-signatures">Type signatures</a></li><li class="toc-entry"><a href="#conditional-imports">Conditional imports</a></li><li class="toc-entry"><a href="#virtual-dispatch-and-mocking">Virtual dispatch and mocking</a></li><li class="toc-entry"><a href="#non-native-apis">Non-native APIs</a></li><li class="toc-entry"><a href="#zones">Zones</a></li></ul></li><li class="toc-entry"><a href="#helpers">Helpers</a></li><li class="toc-entry"><a href="#examples">Examples</a></li></ul><span class="site-toc--inline__toggle toc-toggle-more-items"><i class="material-symbols">more_horiz</i></span></div><p>Dart's <a href="https://pub.dev/packages/web"><code>package:web</code></a> exposes access to browser APIs, enabling interop between Dart applications and the web. Use <code>package:web</code> to interact with the browser and manipulate objects and elements in the DOM.</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'package:web/web.dart'</span><span style="color:#222222">;</span></span> <span class="line"></span> <span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> main</span><span style="color:#222222">() {</span></span> <span class="line"><span style="color:#D43324"> final</span><span style="color:#222222"> div = document.</span><span style="color:#6200EE">querySelector</span><span style="color:#222222">(</span><span style="color:#11796D">'div'</span><span style="color:#222222">)!;</span></span> <span class="line"><span style="color:#222222"> div.text = </span><span style="color:#11796D">'Text set at </span><span style="color:#11796D">${</span><span style="color:#0468D7">DateTime</span><span style="color:#11796D">.</span><span style="color:#6200EE">now</span><span style="color:#11796D">()}</span><span style="color:#11796D">'</span><span style="color:#222222">;</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><aside class="alert alert-warning"><div class="alert-header"><span class="material-symbols" aria-hidden="true">error</span> <span>Important</span></div><div class="alert-content"><p>If you maintain a public Flutter package that uses <code>dart:html</code> or any of the other Dart SDK web libraries, <strong>you should migrate to <code>package:web</code> as soon as possible</strong>. <code>package:web</code> is replacing <code>dart:html</code> and other web libraries as Dart's web interop solution long-term. Read the <strong><code>package:web</code> vs <code>dart:html</code></strong> section for more information.</p></div></aside><div class="header-wrapper"><h2 id="package-web-vs-dart-html"><code>package:web</code> vs <code>dart:html</code></h2><a class="heading-link" href="#package-web-vs-dart-html" aria-label="Link to 'package:web vs dart:html' section">#</a></div><p>The goal of <code>package:web</code> is to revamp how Dart exposes web APIs by addressing several concerns with the existing Dart web libraries:</p><ol><li><p><strong>Wasm compatibility</strong></p><p>Packages can only be compatible with <a href="/web/wasm">Wasm</a> if they use <a href="https://api.dart.dev/dart-js_interop/dart-js_interop-library.html"><code>dart:js_interop</code></a> and <a href="https://api.dart.dev/dart-js_interop_unsafe/dart-js_interop_unsafe-library.html"><code>dart:js_interop_unsafe</code></a>. <code>package:web</code> is based on <code>dart:js_interop</code>, so by default, it's supported on <code>dart2wasm</code>.</p><p>Dart core web libraries, like <a href="https://api.dart.dev/dart-html/dart-html-library.html"><code>dart:html</code></a> and <a href="https://api.dart.dev/dart-svg/dart-svg-library.html"><code>dart:svg</code></a>, are deprecated and <strong>not supported</strong> when compiling to Wasm.</p></li><li><p><strong>Staying modern</strong></p><p><code>package:web</code> uses the <a href="https://www.npmjs.com/package/@webref/idl">Web IDL</a> to automatically generate <a href="/interop/js-interop/usage#interop-members">interop members</a> and <a href="/interop/js-interop/usage#interop-types">interop types</a> for each declaration in the IDL. Generating references directly, as opposed to the additional members and abstractions in <code>dart:html</code>, allows <code>package:web</code> to be more concise, easier to understand, more consistent, and more able to stay up-to-date with the future of Web developments.</p></li><li><p><strong>Versioning</strong></p><p>Because it's a package, <code>package:web</code> can be versioned more easily than a library like <code>dart:html</code> and avoid breaking user code as it evolves. It also makes the code less exclusive and more open to contributions. Developers can create <a href="/interop/js-interop/usage">alternative interop declarations</a> of their own and use them together with <code>package:web</code> without conflict.</p></li></ol><hr><p>These improvements naturally result in some implementation differences between <code>package:web</code> and <code>dart:html</code>. The changes that affect existing packages the most, like IDL <a href="#renames">renames</a> and <a href="#type-tests">type tests</a>, are addressed in the migration sections that follow. While we only refer to <code>dart:html</code> for brevity, the same migration patterns apply to any other Dart core web library like <code>dart:svg</code>.</p><div class="header-wrapper"><h2 id="migrating-from-dart-html">Migrating from <code>dart:html</code></h2><a class="heading-link" href="#migrating-from-dart-html" aria-label="Link to 'Migrating from dart:html' section">#</a></div><p>Remove the <code>dart:html</code> import and replace it with <code>package:web/web.dart</code>:</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'dart:html'</span><span style="color:#D43324"> as</span><span style="color:#222222"> html; </span><span style="color:#6E6E70">// Remove</span></span> <span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'package:web/web.dart'</span><span style="color:#D43324"> as</span><span style="color:#222222"> web; </span><span style="color:#6E6E70">// Add</span></span></code></pre></div></div><p>Add <code>web</code> to the <code>dependencies</code> in your pubspec:</p><div class="code-block-wrapper language-console"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#222222">dart pub add web</span></span></code></pre></div></div><p>The following sections cover some of the common migration issues from <code>dart:html</code> to <code>package:web</code>.</p><p>For any other migration issues, check the <a href="https://github.com/dart-lang/web">dart-lang/web</a> repo and file an issue.</p><div class="header-wrapper"><h3 id="renames">Renames</h3><a class="heading-link" href="#renames" aria-label="Link to 'Renames' section">#</a></div><p>Many of the symbols in <code>dart:html</code> were renamed from their original IDL declaration to align more with Dart style. For example, <code>appendChild</code> became <code>append</code>, <code>HTMLElement</code> became <code>HtmlElement</code>, etc.</p><p>In contrast, to reduce confusion, <code>package:web</code> uses the original names from the IDL definitions. A <code>dart fix</code> is available to convert types that have been renamed between <code>dart:html</code> and <code>package:web</code>.</p><p>After changing the import, any renamed objects will be new "undefined" errors. You can address these either:</p><ul><li>From the CLI, by running <code>dart fix --dry-run</code>.</li><li>In your IDE, by selecting the <code>dart fix</code>: <strong>Rename to '<code>package:web name</code>'</strong>.</li></ul><p>The <code>dart fix</code> covers many of the common type renames. If you come across a <code>dart:html</code> type without a <code>dart fix</code> to rename it, first let us know by filing an <a href="https://github.com/dart-lang/web/issues/new">issue</a>.</p><p>Then, you can try manually discovering the <code>package:web</code> type name of an existing <code>dart:html</code> member by looking up its definition. The value of the <code>@Native</code> annotation on a <code>dart:html</code> member definition tells the compiler to treat any JS object of that type as the Dart class that it annotates. For example, the <code>@Native</code> annotation tells us that the native JS name of <code>dart:html</code>'s <code>HtmlElement</code> member is <code>HTMLElement</code>, so the <code>package:web</code> name will also be <code>HTMLElement</code>:</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">@Native</span><span style="color:#222222">(</span><span style="color:#11796D">"HTMLElement"</span><span style="color:#222222">)</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> HtmlElement</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Element</span><span style="color:#D43324"> implements</span><span style="color:#0468D7"> NoncedElement</span><span style="color:#222222"> { }</span></span></code></pre></div></div><p>To find the <code>dart:html</code> definition for an undefined member in <code>package:web</code>, try either of the following methods:</p><ul><li>Ctrl or command click the undefined name in the IDE and choose <strong>Go to Definition</strong>.</li><li>Search for the name in the <a href="https://api.dart.dev/dart-html/dart-html-library.html"><code>dart:html</code> API docs</a> and check its page under <em>Annotations</em>.</li></ul><p>Similarly, you might find an undefined <code>package:web</code> API whose corresponding <code>dart:html</code> member's definition uses the keyword <code>native</code>. Check if the definition uses the <code>@JSName</code> annotation for a rename; the value of the annotation will tell you the name the member uses in <code>package:web</code>:</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">@JSName</span><span style="color:#222222">(</span><span style="color:#11796D">'appendChild'</span><span style="color:#222222">)</span></span> <span class="line"><span style="color:#0468D7">Node</span><span style="color:#6200EE"> append</span><span style="color:#222222">(</span><span style="color:#0468D7">Node</span><span style="color:#222222"> node) </span><span style="color:#D43324">native</span><span style="color:#222222">;</span></span></code></pre></div></div><p><code>native</code> is an internal keyword that means the same as <code>external</code> in this context.</p><div class="header-wrapper"><h3 id="type-tests">Type tests</h3><a class="heading-link" href="#type-tests" aria-label="Link to 'Type tests' section">#</a></div><p>It's common for code that uses <code>dart:html</code> to utilize runtime checks like <code>is</code>. When used with a <code>dart:html</code> object, <code>is</code> and <code>as</code> verify that the object is the JS type within the <code>@Native</code> annotation. In contrast, all <code>package:web</code> types are reified to <a href="https://api.dart.dev/dart-js_interop/JSObject-extension-type.html"><code>JSObject</code></a>. This means a runtime type test will result in different behavior between <code>dart:html</code> and <code>package:web</code> types.</p><p>To be able to perform type tests, migrate any <code>dart:html</code> code using <code>is</code> type tests to use <a href="https://api.dart.dev/dart-js_interop/JSAnyUtilityExtension.html#instance-methods">interop methods</a> like <code>instanceOfString</code> or the more convenient and typed <a href="https://api.dart.dev/dart-js_interop/JSAnyUtilityExtension/isA.html"><code>isA</code></a> helper (available from Dart 3.4 onward). The <a href="/interop/js-interop/js-types#compatibility-type-checks-and-casts">Compatibility, type checks, and casts</a> section of the JS types page covers alternatives in detail.</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#222222">obj is </span><span style="color:#0468D7">Window</span><span style="color:#222222">; </span><span style="color:#6E6E70">// Remove</span></span> <span class="line"><span style="color:#222222">obj.</span><span style="color:#6200EE">instanceOfString</span><span style="color:#222222">(</span><span style="color:#11796D">'Window'</span><span style="color:#222222">); </span><span style="color:#6E6E70">// Add</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="type-signatures">Type signatures</h3><a class="heading-link" href="#type-signatures" aria-label="Link to 'Type signatures' section">#</a></div><p>Many APIs in <code>dart:html</code> support various Dart types in their type signatures. Because <code>dart:js_interop</code> <a href="/interop/js-interop/js-types#requirements-on-external-declarations-and-function-tojs">restricts</a> the types that can be written, some of the members in <code>package:web</code> will now require you to <em>convert</em> the value before calling the member. Learn how to use interop conversion methods from the <a href="/interop/js-interop/js-types#conversions">Conversions</a> section of the JS types page.</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#222222">window.</span><span style="color:#6200EE">addEventListener</span><span style="color:#222222">(</span><span style="color:#11796D">'click'</span><span style="color:#222222">, callback); </span><span style="color:#6E6E70">// Remove</span></span> <span class="line"><span style="color:#222222">window.</span><span style="color:#6200EE">addEventListener</span><span style="color:#222222">(</span><span style="color:#11796D">'click'</span><span style="color:#222222">, callback.toJS); </span><span style="color:#6E6E70">// Add</span></span></code></pre></div></div><p>Generally, you can spot which methods need a conversion because they'll be flagged with some variation of the exception:</p><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>A value of type '...' can't be assigned to a variable of type 'JSFunction?'</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="conditional-imports">Conditional imports</h3><a class="heading-link" href="#conditional-imports" aria-label="Link to 'Conditional imports' section">#</a></div><p>It's common for code to use a conditional import based on whether <code>dart:html</code> is supported to differentiate between native and web:</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">export</span><span style="color:#11796D"> 'src/hw_none.dart'</span></span> <span class="line"><span style="color:#D43324"> if</span><span style="color:#222222"> (dart.library.io) </span><span style="color:#11796D">'src/hw_io.dart'</span></span> <span class="line"><span style="color:#D43324"> if</span><span style="color:#222222"> (dart.library.html) </span><span style="color:#11796D">'src/hw_html.dart'</span><span style="color:#222222">;</span></span></code></pre></div></div><p>However, since <code>dart:html</code> is deprecated and not supported when compiling to Wasm, the correct alternative now is to use <code>dart.library.js_interop</code> to differentiate between native and web:</p> <?code-excerpt "create_libraries/lib/hw_mp.dart (export)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">export</span><span style="color:#11796D"> 'src/hw_none.dart'</span><span style="color:#6E6E70"> // Stub implementation</span></span> <span class="line"><span style="color:#D43324"> if</span><span style="color:#222222"> (dart.library.io) </span><span style="color:#11796D">'src/hw_io.dart'</span><span style="color:#6E6E70"> // dart:io implementation</span></span> <span class="line"><span style="color:#D43324"> if</span><span style="color:#222222"> (dart.library.js_interop) </span><span style="color:#11796D">'src/hw_web.dart'</span><span style="color:#222222">; </span><span style="color:#6E6E70">// package:web implementation</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="virtual-dispatch-and-mocking">Virtual dispatch and mocking</h3><a class="heading-link" href="#virtual-dispatch-and-mocking" aria-label="Link to 'Virtual dispatch and mocking' section">#</a></div><p><code>dart:html</code> classes supported virtual dispatch, but because JS interop uses extension types, virtual dispatch is <a href="/language/extension-types">not possible</a>. Similarly, <code>dynamic</code> calls with <code>package:web</code> types won't work as expected (or, they might continue to work just by chance, but will stop when <code>dart:html</code> is removed), as their members are only available statically. Migrate all code that relies on virtual dispatch to avoid this issue.</p><p>One use case of virtual dispatch is mocking. If you have a mocking class that <code>implements</code> a <code>dart:html</code> class, it can't be used to implement a <code>package:web</code> type. Instead, prefer mocking the JS object itself. See the <a href="/interop/js-interop/mock">mocking tutorial</a> for more information.</p><div class="header-wrapper"><h3 id="non-native-apis">Non-<code>native</code> APIs</h3><a class="heading-link" href="#non-native-apis" aria-label="Link to 'Non-native APIs' section">#</a></div><p><code>dart:html</code> classes may also contain APIs that have a non-trivial implementation. These members may or may not exist in the <code>package:web</code> <a href="#helpers">helpers</a>. If your code relies on the specifics of that implementation, you may be able to copy the necessary code. However, if you think that's not tractable or if that code would be beneficial for other users as well, consider filing an issue or uploading a pull request to <a href="https://github.com/dart-lang/web"><code>package:web</code></a> to support that member.</p><div class="header-wrapper"><h3 id="zones">Zones</h3><a class="heading-link" href="#zones" aria-label="Link to 'Zones' section">#</a></div><p>In <code>dart:html</code>, callbacks are automatically zoned. This is not the case in <code>package:web</code>. There is no automatic binding of callbacks in the current zone.</p><p>If this matters for your application, you can still use zones, but you will have to <a href="/libraries/async/zones">write them yourself</a> by binding the callback. See <a href="https://github.com/dart-lang/sdk/issues/54507">#54507</a> for more details. There is no conversion API or <a href="#helpers">helper</a> available yet to automatically do this.</p><div class="header-wrapper"><h2 id="helpers">Helpers</h2><a class="heading-link" href="#helpers" aria-label="Link to 'Helpers' section">#</a></div><p>The core of <code>package:web</code> contains <code>external</code> interop members, but doesn't provide other functionality that <code>dart:html</code> provided by default. To mitigate these differences, <code>package:web</code> contains <a href="https://github.com/dart-lang/web/tree/main/web/lib/src/helpers"><code>helpers</code></a> for additional support in handling a number of use cases that aren't directly available through the core interop. The helper library contains various members to expose some legacy features from the Dart web libraries.</p><p>For example, the core <code>package:web</code> only has support for adding and removing event listeners. Instead, you can use <a href="https://github.com/dart-lang/web/blob/main/web/lib/src/helpers/events/streams.dart">stream helpers</a> that makes it easy to subscribe to events with Dart <code>Stream</code>s without writing that code yourself.</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">// Original dart:html version:</span></span> <span class="line"><span style="color:#D43324">final</span><span style="color:#222222"> htmlInput = </span><span style="color:#0468D7">InputElement</span><span style="color:#222222">();</span></span> <span class="line"><span style="color:#D43324">await</span><span style="color:#222222"> htmlInput.onBlur.first;</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70">// Migrated package:web version:</span></span> <span class="line"><span style="color:#D43324">final</span><span style="color:#222222"> webInput = </span><span style="color:#0468D7">HTMLInputElement</span><span style="color:#222222">();</span></span> <span class="line"><span style="color:#D43324">await</span><span style="color:#222222"> webInput.onBlur.first;</span></span></code></pre></div></div><p>You can find all the helpers and their documentation in the repo at <a href="https://github.com/dart-lang/web/tree/main/web/lib/src/helpers"><code>package:web/helpers</code></a>. They will continuously be updated to aid users in migration and make it easier to use the web APIs.</p><div class="header-wrapper"><h2 id="examples">Examples</h2><a class="heading-link" href="#examples" aria-label="Link to 'Examples' section">#</a></div><p>Here are some examples of packages that have been migrated from <code>dart:html</code> to <code>package:web</code>:</p><ul><li><a href="https://github.com/flutter/packages/pull/5451/files">Upgrading <code>url_launcher</code> to <code>package:web</code></a></li></ul><nav id="subnav"><ul><li class="previous"><a href="/interop/js-interop/past-js-interop">&lang;  Past JS interop</a></li><li class="next"></li></ul></nav><p id="page-github-links"><span>Unless stated otherwise, the documentation on this site reflects Dart 3.7.0. Page last updated on 2025-01-31.</span> <a href="https://github.com/dart-lang/site-www/tree/main/src/content/interop/js-interop/package-web.md" target="_blank" rel="noopener">View source</a> <span>or </span><a href="https://github.com/dart-lang/site-www/issues/new?template=1_page_issue.yml&page-url=https://dart.dev/interop/js-interop/package-web/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/interop/js-interop/package-web.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</p></div></article></main></div><footer id="page-footer"><div class="footer-section footer-main"><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart" width="164"></a><div class="footer-social-links"><a href="https://medium.com/dartlang" target="_blank" rel="noopener" title="Dart's Medium publication"><svg><use href="/assets/img/social/medium.svg#medium"></use></svg> </a><a href="https://github.com/dart-lang" target="_blank" rel="noopener" title="Dart's GitHub organization"><svg><use href="/assets/img/social/github.svg#github"></use></svg> </a><a href="https://bsky.app/profile/dart.dev" target="_blank" rel="noopener" title="Dart's Bluesky profile"><svg><use href="/assets/img/social/bluesky.svg#bluesky"></use></svg> </a><a href="https://twitter.com/dart_lang" target="_blank" rel="noopener" title="Dart's X (Twitter) profile"><svg><use href="/assets/img/social/x.svg#x"></use></svg></a></div></div><div class="footer-section footer-tray"><div class="footer-licenses">Except as otherwise noted, this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>, and code samples are licensed under the <a href="https://opensource.org/licenses/BSD-3-Clause">3-Clause BSD License</a>.</div><div class="footer-utility-links"><ul><li><a href="/terms" title="Terms of use">Terms</a></li><li><a href="https://policies.google.com/privacy" target="_blank" rel="noopener" title="Privacy policy">Privacy</a></li><li><a href="/security" title="Security philosophy and practices">Security</a></li></ul></div></div></footer></div></body></html>