description

# dart:js_interop library

Interoperability, "interop" for short, with JavaScript and browser APIs.

JavaScript interop allows a Dart program to interact with a JavaScript runtime. This can, for example, be to access JavaScript declarations and interact with JavaScript values, or to adapt Dart values so that they can be passed to and used by JavaScript code.

This JavaScript interop library works by introducing an abstraction over JavaScript values, a Dart type hierarchy ("JS types") which mirrors known JavaScript types, and a framework for introducing new Dart types that bind Dart type declarations to JavaScript values and external member declarations to JavaScript APIs.

This abstraction allows the same interop API to be used both when the Dart code is compiled to JavaScript and when compiled to Wasm.

See https://dart.dev/interop/js-interop for more details on usage, types, and previous JavaScript interop.

Note

The types defined in this library only provide static guarantees. The runtime types differ based on the backend, so it is important to rely on static functionality like the conversion functions. Similarly, don't rely on `is` checks that involve JS types or JS-typed values. Furthermore, `identical` may also return different results for the same JS value depending on the compiler. Use `==` to check for equality of two JS-typed values instead, but do not check for equality between a Dart value and a JS-typed value.

## Classes

JS
  An annotation on a JavaScript interop declaration.
JSExport
  Annotation to allow Dart classes to be wrapped with a JS object using `dart:js_interop`'s `createJSInteropWrapper`.

## Extension Types

ExternalDartReference
  An opaque reference to a Dart object that can be passed to JavaScript.
JSAny
  A non-nullish JavaScript value.
JSArray
  A JavaScript `Array`.
JSArrayBuffer
  A JavaScript `ArrayBuffer`.
JSBigInt
  A JavaScript `BigInt`.
JSBoolean
  A JavaScript boolean.
JSBoxedDartObject
  A Dart object that is wrapped with a JavaScript object so that it can be passed to JavaScript safely.
JSDataView
  A JavaScript `DataView`.
JSExportedDartFunction
  A JavaScript function created from a Dart function.
JSFloat32Array
  A JavaScript `Float32Array`.
JSFloat64Array
  A JavaScript `Float64Array`.
JSFunction
  A JavaScript `Function` value.
JSInt16Array
  A JavaScript `Int16Array`.
JSInt32Array
  A JavaScript `Int32Array`.
JSInt8Array
  A JavaScript `Int8Array`.
JSIterable
  A JSIterableProtocol whose iterator is a JSIterator.
JSIterableProtocol
  The synchronous JS iterable protocol.
JSIterator
  A proper JS iterator.
JSIteratorProtocol
  The synchronous JS iterator protocol.
JSIteratorResult
  A synchronous JS `IteratorResult`.
JSNumber
  A JavaScript number.
JSObject
  A JavaScript `Object`.
JSPromise
  A JavaScript `Promise` or a promise-like object.
JSString
  A JavaScript string.
JSSymbol
  A JavaScript `Symbol`.
JSTypedArray
  Abstract supertype of all JavaScript typed arrays.
JSUint16Array
  A JavaScript `Uint16Array`.
JSUint32Array
  A JavaScript `Uint32Array`.
JSUint8Array
  A JavaScript `Uint8Array`.
JSUint8ClampedArray
  A JavaScript `Uint8ClampedArray`.

## Extensions

BoolToJSBoolean on bool
  Conversions from bool to JSBoolean.
ByteBufferToJSArrayBuffer on ByteBuffer
  Conversions from ByteBuffer to JSArrayBuffer.
ByteDataToJSDataView on ByteData
  Conversions from ByteData to JSDataView.
DoubleToJSNumber on double
  Conversions from double to JSNumber.
ExternalDartReferenceToObject on ExternalDartReference<T>
  Conversions from ExternalDartReference to the value of type `T`.
Float32ListToJSFloat32Array on Float32List
  Conversions from Float32List to JSFloat32Array.
Float64ListToJSFloat64Array on Float64List
  Conversions from Float64List to JSFloat64Array.
FunctionToJSExportedDartFunction on T
  Conversions from `T` to `JSExportedDartFunction<T>`.
FutureOfJSAnyToJSPromise on Future<T>
  Conversions from Future to JSPromise where the Future returns a value.
FutureOfVoidToJSPromise on Future<void>
  Conversions from Future to JSPromise where the Future does not return a value.
Int16ListToJSInt16Array on Int16List
  Conversions from Int16List to JSInt16Array.
Int32ListToJSInt32Array on Int32List
  Conversions from Int32List to JSInt32Array.
Int8ListToJSInt8Array on Int8List
  Conversions from Int8List to JSInt8Array.
IterableToJSIterable on Iterable<T>
  Conversion from Iterable to JSIterable.
IteratorToJSIterator on Iterator<T>
  Conversion from Iterator to JSIterator.
JSAnyOperatorExtension on JSAny?
  General-purpose JavaScript operators.
JSAnyUtilityExtension on JSAny?
  Common utility functions that are useful for any JavaScript value.
JSArrayBufferToByteBuffer on JSArrayBuffer
  Conversions from JSArrayBuffer to ByteBuffer.
JSArrayToList on JSArray<T>
  Conversions from JSArray to List.
JSBooleanToBool on JSBoolean
  Conversions from JSBoolean to bool.
JSBoxedDartObjectToObject on JSBoxedDartObject
  Conversions from JSBoxedDartObject to Object.
JSDataViewToByteData on JSDataView
  Conversions from JSDataView to ByteData.
JSExportedDartFunctionToFunction on JSExportedDartFunction<T>
  Conversions from `JSExportedDartFunction<T>` to `T`.
JSFloat32ArrayToFloat32List on JSFloat32Array
  Conversions from JSFloat32Array to Float32List.
JSFloat64ArrayToFloat64List on JSFloat64Array
  Conversions from JSFloat64Array to Float64List.
JSFunctionUtilExtension on JSFunction<Function>
  Utility extensions for JSFunction.
JSInt16ArrayToInt16List on JSInt16Array
  Conversions from JSInt16Array to Int16List.
JSInt32ArrayToInt32List on JSInt32Array
  Conversions from JSInt32Array to Int32List.
JSInt8ArrayToInt8List on JSInt8Array
  Conversions from JSInt8Array to Int8List.
JSIterableToIterable on JSIterable<T>
  Conversion from JSIterable to Iterable.
JSIteratorToIterator on JSIterator<T>
  Conversion from JSIterator to Iterator.
JSNumberToNumber on JSNumber
  Conversions from JSNumber to double or int.
JSPromiseToFuture on JSPromise<T>
  Conversions from JSPromise to Future.
JSStringToString on JSString
  Conversions from JSString to String.
JSUint16ArrayToUint16List on JSUint16Array
  Conversions from JSUint16Array to Uint16List.
JSUint32ArrayToUint32List on JSUint32Array
  Conversions from JSUint32Array to Uint32List.
JSUint8ArrayToUint8List on JSUint8Array
  Conversions from JSUint8Array to Uint8List.
JSUint8ClampedArrayToUint8ClampedList on JSUint8ClampedArray
  Conversions from JSUint8ClampedArray to Uint8ClampedList.
ListToJSArray on List<T>
  Conversions from List to JSArray.
NullableObjectUtilExtension on Object?
  Common utility functions for `Object?`s.
NullableUndefineableJSAnyExtension on JSAny?
  Helper members to determine if a value is JavaScript `undefined` or `null`.
NumToJSExtension on num
  Conversions from num to JSNumber.
ObjectToExternalDartReference on T
  Conversions from a value of type `T` to ExternalDartReference.
ObjectToJSBoxedDartObject on Object
  Conversions from Object to JSBoxedDartObject.
StringToJSString on String
  Conversions from String to JSString.
Uint16ListToJSUint16Array on Uint16List
  Conversions from Uint16List to JSUint16Array.
Uint32ListToJSUint32Array on Uint32List
  Conversions from Uint32List to JSUint32Array.
Uint8ClampedListToJSUint8ClampedArray on Uint8ClampedList
  Conversions from Uint8ClampedList to JSUint8ClampedArray.
Uint8ListToJSUint8Array on Uint8List
  Conversions from Uint8List to JSUint8Array.

## Constants

anonymous → const _Anonymous
  An annotation that indicates a JS annotated class is structural and does not have a known JavaScript prototype.
staticInterop → const _StaticInterop
  staticInterop enables the JS annotated class to be treated as a "static" interop class.

## Properties

globalContext → JSObject
  The global scope that is used to find user-declared interop members.
  no setter

## Functions

createJSInteropWrapper<T extends Object>(T dartObject, [JSObject? prototype = null]) → JSObject
  Given a instance of a Dart class that contains an `@JSExport` annotation, creates a JavaScript object that wraps the given Dart object.
importModule(JSAny moduleName) → JSPromise<JSObject>
  Dynamically imports a JavaScript module with the given `moduleName` using the JavaScript `import()` syntax.
jsIdentical(Object? a, Object? b) → bool
  Returns true if the underlying JavaScript values of `a` and `b` are identical.

## Typedefs

JSVoid = JSVoidType
  JS type equivalent for `undefined` for interop member return types.

## Exceptions / Errors

NullRejectionException
  Exception for when a JSPromise that is converted via JSPromiseToFuture.toDart is rejected with a `null` or `undefined` value.