Dart JS Interop: Using `dart:html` Types Explained

Aug 15, 2025 by Pedro Alvarez 51 views

Demystifying Dart JS Interop: Can You Use `dart:html` Types?

Hey everyone! Today, we're diving deep into the fascinating world of Dart's JavaScript interop, specifically focusing on whether you can use types from the dart:html library within your JS interop code. This is a crucial topic for anyone building web applications with Dart that need to interact with JavaScript libraries or the browser's DOM. Let's get started!

Introduction to Dart JS Interop

Before we get into the specifics, let's briefly recap what Dart JS interop is all about. Dart JS interop is a powerful mechanism that allows Dart code to seamlessly interact with JavaScript code. This means you can leverage existing JavaScript libraries, frameworks, or even browser APIs directly from your Dart applications. This opens up a world of possibilities, allowing you to build rich and interactive web experiences.

When working with JS interop, it's essential to understand how Dart types map to JavaScript types and vice versa. This understanding is critical for ensuring smooth communication between your Dart and JavaScript code. Dart provides several annotations and mechanisms to help you define these mappings, including @JSExport, @JSImport, and extension types. These tools enable you to create a bridge between the two worlds, making it feel like you're working with a single unified environment.

One common use case for JS interop is manipulating the DOM (Document Object Model) in a web browser. The DOM is the structure that represents the HTML elements on a webpage, and JavaScript is often used to interact with it. Dart's dart:html library provides a set of classes and functions for working with the DOM, but sometimes you might need to use JavaScript libraries that also interact with the DOM. This is where JS interop comes in handy, allowing you to seamlessly integrate Dart's DOM manipulation capabilities with JavaScript's.

The Core Question: `dart:html` and JS Interop

So, the big question we're tackling today is: Can you use types from the dart:html library in your JS interop types? This question often arises when developers try to pass DOM elements (like DivElement, InputElement, etc.) between Dart and JavaScript code. The answer, as we'll explore, is a bit nuanced and depends on the specific context and tools you're using.

According to an error message found in the Dart SDK repository, dart:html types are allowed in JS interop members when using dart2js. This is the Dart-to-JavaScript compiler that's commonly used for web applications. However, as a user pointed out, simply allowing the types doesn't guarantee that the code will work as expected. Let's delve into why this might be the case and how to address it.

The initial confusion often stems from the fact that while the Dart compiler might allow dart:html types in JS interop declarations, the underlying JavaScript environment needs to know how to handle these types. Dart's dart:html types are Dart-specific representations of DOM elements. JavaScript, on the other hand, has its own native DOM element types. The key is to ensure that these types are correctly converted and understood on both sides of the interop bridge.

Diving into the Code Example

To illustrate this issue, let's consider the code snippet provided in the original question:

import 'dart:html';
import 'dart:js_interop';

extension type ET._(JSObject _) implements JSObject {
  external ET.fromElement(Element e);
}

main() {
  Element e1 = DivElement();
  ET et1 = ET.fromElement(e1); // TypeError: init.G.ET is not a constructor
}

In this example, we're defining an extension type ET that wraps a JSObject. The intention is to create an ET instance from a dart:html Element. However, when the code is executed, it throws a TypeError: init.G.ET is not a constructor. This error message indicates that the JavaScript code doesn't know how to construct an instance of ET from the given Element.

Let's break down why this is happening. The ET.fromElement constructor is declared as external, which means that its implementation is expected to be provided by JavaScript. However, in this case, there's no JavaScript code that knows how to handle a Dart Element and create an ET instance. The JavaScript runtime doesn't automatically understand how to convert a Dart DivElement to a JavaScript object that ET can wrap.

This example highlights a crucial point: when working with dart:html types in JS interop, you need to ensure that there's a proper conversion mechanism in place. You can't simply pass a Dart Element to JavaScript and expect it to work without any additional handling.

Understanding the Error Message

The error message "TypeError: init.G.ET is not a constructor" is a common one in JavaScript and often indicates that you're trying to use something as a constructor (i.e., calling it with new) that isn't actually a constructor function. In the context of Dart JS interop, this usually means that the JavaScript side doesn't have a corresponding constructor or factory function that can handle the Dart type you're passing.

In our example, the ET.fromElement constructor is declared as external, which implies that the actual implementation should be provided by JavaScript. Since there's no JavaScript code to handle the conversion of a Dart Element to an ET instance, the JavaScript runtime throws a TypeError. It's essentially saying, "I don't know how to build an ET from this Element!"

This type of error is a valuable clue when debugging JS interop issues. It tells you that the problem likely lies in the interaction between Dart and JavaScript, specifically in how types are being converted or handled. When you encounter this error, it's a good idea to double-check your interop declarations and ensure that the JavaScript side has the necessary functions or constructors to work with the Dart types you're using.

Solutions and Best Practices

So, how do we solve this issue and successfully use dart:html types in JS interop? Here are a few strategies and best practices to keep in mind:

1. Explicit Conversion

The most common approach is to perform explicit conversion between Dart and JavaScript types. Instead of directly passing a Dart Element to JavaScript, you can extract the underlying JavaScript object using the js_util package. This package provides functions like jsify and getObject that allow you to convert Dart objects to their JavaScript equivalents and vice versa.

For example, you can use e.jsObject to get the JavaScript representation of a Dart Element. Then, you can pass this JavaScript object to your JavaScript code. On the JavaScript side, you'll be working with a standard DOM element, which is easily manipulated using JavaScript APIs.

import 'dart:html';
import 'dart:js_interop';
import 'package:js/js_util.dart' as js_util;

extension type ET._(JSObject _) implements JSObject {
  external static ET fromElement(JSObject e);

  @JSExport()
  static ET fromJsElement(Element e) {
    return ET.fromElement(e.jsObject);
  }
}

main() {
  Element e1 = DivElement();
  ET et1 = ET.fromJsElement(e1); // This should work with proper JS implementation
}

2. JavaScript Facades

Another powerful technique is to use JavaScript facades. A facade is a Dart class or extension type that mirrors the API of a JavaScript object. This allows you to interact with JavaScript objects in a type-safe manner from your Dart code. You can define methods and properties in your Dart facade that correspond to the methods and properties of the JavaScript object.

When creating facades for dart:html types, you can map Dart methods to JavaScript methods that manipulate the DOM. This provides a clean and intuitive way to work with DOM elements from Dart, while still leveraging the power of JS interop.

3. Custom JavaScript Interop Code

In some cases, you might need to write custom JavaScript code to handle the conversion between Dart and JavaScript types. This is particularly useful when dealing with complex types or when you need to perform specific operations on the JavaScript side.

You can define JavaScript functions that accept Dart types as arguments and return JavaScript types. These functions can then be called from your Dart code using JS interop. This gives you fine-grained control over the type conversion process and allows you to tailor the interaction between Dart and JavaScript to your specific needs.

4. Leveraging `package:web`

The package:web provides a set of low-level primitives and utilities for web development in Dart, offering a more direct way to interact with the browser's APIs. It's an alternative to dart:html that aligns more closely with web standards and can sometimes simplify JS interop scenarios.

If you're finding it challenging to work with dart:html types in JS interop, exploring package:web might offer a more streamlined approach. It gives you greater control over the underlying web platform APIs and can reduce the need for complex type conversions.

Key Takeaways

Let's summarize the key takeaways from our exploration of dart:html types and JS interop:

dart:html types are allowed in JS interop members (in dart2js).
However, simply allowing the types doesn't guarantee that the code will work without proper conversion mechanisms.
The error message "TypeError: init.G.ET is not a constructor" often indicates a mismatch between Dart and JavaScript types.
Explicit conversion, JavaScript facades, custom JavaScript interop code, and package:web are all valuable tools for working with dart:html types in JS interop.
Always ensure that there's a clear and well-defined conversion process between Dart and JavaScript types to avoid runtime errors.

Conclusion

Working with dart:html types in JS interop can be a bit tricky, but with the right techniques and understanding, you can seamlessly integrate Dart and JavaScript code in your web applications. Remember to focus on explicit type conversion, leverage JavaScript facades when appropriate, and consider using custom JavaScript interop code for complex scenarios. By following these best practices, you'll be well-equipped to build powerful and interactive web experiences with Dart and JavaScript.

So, guys, I hope this article has cleared up some of the confusion around using dart:html types in JS interop. Keep experimenting, keep learning, and keep building awesome things with Dart! If you have any questions or comments, feel free to drop them below. Happy coding!