Embedding Dart in HTML
Written by Sigmund Cherem, Vijay Menon, and Seth Ladd
October 2011 (updated December 2014)
If your Dart file is
- Load your Dart app with a
<script type="application/dart">tag (only one per HTML page).
- Follow that tag with a <script> tag for the
Here is a minimal example, which works in all browsers (even if they don’t support the Dart VM):
Dart MIME type and the <script> tag
script tags provide a
type attribute to define the language of the script.
For Dart, this attribute has the value
Here is an example:
<script type="application/dart" src="app.dart"></script>
The Dart app must have a visible top-level function called
The browser invokes
main() when the DOM content is loaded (but see
caveat in the next section).
You should use only one
<script type="application/dart"> inside the HTML
the only Dart app on the page.
Dart semantics in HTML
The precise semantics of Dart execution on an HTML page are evolving and likely to change by the time Dart is natively supported in a production browser.
Currently, your Dart app’s
main() function is run after DOM content
is loaded, but the exact timing is undefined (e.g., with respect to
main() synchronously during HTML parsing instead of waiting for DOM
content to load.
As such, we recommend the following:
- Restrict your application to a single Dart script per document.
- Place your Dart script at the end of your document’s body (followed only by the dart.js script if you choose to use that).
- Do not use async or defer attributes on your Dart script tag at this point.
- Do not rely upon script injection of Dart code.
The dart.js script
Use the dart.js script, part of the browser package, to run your app in browsers that don’t have a Dart VM. The dart.js script allows you to use the same HTML page for both Dartium and other browsers.
If no Dart VM is detected in the browser, the dart.js script swaps out the
application/dart script for a
The dart.js script tag must come after the Dart script tag.
To get a copy of the dart.js file, you can use the pub package manager. Here’s how:
Add the following to your application’s pubspec.yaml, replacing the version range with the appropriate version:
dependencies: browser: ">=0.10.0 <0.11.0"
Use a relative script tag to point to the installed version:
A single script tag
Web components and HTML imports are an important caveat to the one script per document rule. For example, the Polymer.dart framework uses HTML imports to allow developers to include HTML components into a Dart application. Dart scripts in imported HTML documents are injected into the main application. See the Polymer.dart documentation for more details.
top-level Dart constructs (such as interfaces, classes, and functions)
Each Dart application (defined via a script tag)
provides an explicit
main() entry point
that is invoked by the browser when it is ready to run.
Currently, the Dart app’s
is invoked after the page’s DOM is loaded.
No inline event listeners
We disallow inline event listeners of the form:
<div onclick="foo()">Click this text.</div>
No script injection of Dart code
We do not currently support or recommend dynamically injecting a
<script> tag that loads Dart code. Recent browser security trends,
like Content Security Policy, actively prevent this practice.