ExternalDartReference<T extends Object?> extension type

An opaque reference to a Dart object that can be passed to JavaScript.

The reference representation depends on the underlying platform. When compiling to JavaScript, a Dart object is a JavaScript object, and can be used directly without any conversions. When compiling to Wasm, an internal Wasm function is used to convert the Dart object to an opaque JavaScript value, which can later be converted back using another internal function. The underlying representation type is nullable, meaning a non-nullable ExternalDartReference may be null.

This interface is a faster alternative to JSBoxedDartObject by not wrapping the Dart object with a JavaScript object. However, unlike JSBoxedDartObject, this value belongs to the Dart runtime, and therefore can not be used as a JS type. This means users cannot declare interop types using this as the representation type or declare interop members on this type. This type is also not a subtype of JSAny. This type can only be used as parameter and return types of external JavaScript interop members or callbacks. Use JSBoxedDartObject to avoid those limitations.

Besides these differences, ExternalDartReference operates functionally the same as JSBoxedDartObject. Use it to pass Dart objects within the same runtime through JavaScript. There are no usable members in the resulting ExternalDartReference.

See ObjectToExternalDartReference.toExternalReference to allow an arbitrary value of type T to be passed to JavaScript.