Pub Package

Introduction

Cross-platform dart:html that works in browser, Flutter, Dart VM, and Node.JS.

The project is licensed under the MIT license.

Issues?

Similar projects

Getting started

1. Add dependency

In pubspec.yaml:

name: example
dependencies:
  universal_html: ^1.0.6

Now you can replace usage of "dart:html" with "package:universal_html/html.dart".

2. Choose library

import 'package:universal_html/html.dart';

This library exports our implementation by default. The library exports dart:html only in browsers.

Getting warnings? If you exchange DOM elements with packages that use dart:html, your IDE/compiler may produce type warnings ("universal_html Element is not dart:html Element"). You can eliminate the warnings by using the package below.

Library that exports dart:html by default

import 'package:universal_html/browser/html.dart';

This library exports dart:html by default. The library exports our implementation only when dart:io is available.

If you use this library:

  • Dart tools may mistakenly think that your package is not compatible with VM/Flutter.
  • Your package will not compile in Node.JS.

3. That's it!

import "package:universal_html/html.dart";

void main() {
  // Create a DOM tree
  final divElement = new DivElement();
  divElement.append(new Element.tag("h1")
    ..classes.add("greeting")
    ..appendText("Hello world!"));

  // Print outer HTML
  print(divElement.outerHtml);
  // --> <div><h1>Hello world</h1></div>

  // Do a CSS query
  print(divElement.querySelector("div > .greeting").text);
  // --> Hello world
}

Manual

Server-side rendering

import 'package:universal_html/driver.dart';
import 'package:universal_html/html.dart';

void main() {
  final renderer = new ServerSideRenderer(webAppMain);
  renderer.bind("localhost", 12345);
}

void webAppMain() {
  document.body.appendText("Hello world!");
}

Creating and using browser simulators

import 'package:universal_html/driver.dart';
import 'package:universal_html/html.dart';

Future main() async {
  // Construct a driver
  final driver = new HtmlDriver(userAgent:"My Hacker News bot");
  
  // Load a document.
  await driver.setDocumentFromUri(Uri.parse("https://news.ycombinator.com/"));
  
  // Select top story
  final topStoryTitle = driver.document.querySelectorAll(".athing > .title").first.text;
  print("Top Hacker News story is: ${topStoryTitle}");
}

Implemented APIs

Principles

  • Our goal is that the implemented APIs behave identically to dart:html code running in Chrome.
  • Non-implemented APIs either throw UnimplementedError or fail silently.
  • We accept pull requests for more API implementations!

An incomplete list

  • Document nodes
    • All the core classes (Node, Element, etc.)
    • Much of the element subclasses (CheckboxInputElement, ResetButtonElement, etc.)
    • Much of the CSS classes (CssStyleDeclaration, etc.)
  • DOM parsing
  • DOM printing
    • element.innerHtml
    • element.outerHtml
  • DOM events
    • For example, element.onClick.listen(...) would receive invocation of element.click().
  • CSS selectors
    • Methods element.querySelector(..), element.querySelectorAll(..), element.matchesSelector(..)
    • Element name (table)
    • Element ID (#id)
    • Element class (.classA.classB)
    • Combinators:
      • element.class#id
      • s0 s1 s2
      • s0 s1 s2
      • s0 > s1 > s2
      • s0 ~ s1 ~ s2
      • s0 + s1 + s2
    • Pseudoselectors:
      • :disabled
      • :first-child
      • :last-child
      • :not(x)
      • :nth-child(5)
      • :nth-child(even)
      • :nth-child(3n+1)
      • :only-child
      • :root
    • Attribute selectors:
      • [name]
      • [name=value]
      • [name~=value]
      • [name|=value]
      • [name^=value]
      • [name$=value]
      • [name*=value]
  • Navigator
    • locale, userAgent, etc.
  • Window
    • console
    • history
      • back(...), pushState(...), etc.
    • location
      • origin, href, etc.
    • localStorage / sessionStorage
      • Stores values in the heap.
  • HttpRequest
    • Does not implement same-origin security policies that browsers have.
  • Related libraries (dart:js, dart:svg, etc.).
    • Just API declarations. Any attempt to use APIs will throw UnimplementedException.
    • Available in:
      • "package:universal_html/indexed_db.dart"
      • "package:universal_html/js.dart"
      • "package:universal_html/js_util.dart"
      • "package:universal_html/svg.dart"

Libraries

browser.html
Exports dart:html. In VM and Flutter, exports our implementation. [...]
browser.indexed_db
Exports dart:indexed_db. In VM and Flutter, exports our implementation.
browser.js
Exports dart:js. In VM and Flutter, exports our implementation. [...]
browser.js_util
Exports dart:js_util. In VM and Flutter, exports our implementation. [...]
browser.svg
Exports dart:svg. In VM and Flutter, exports our implementation.
driver
Creates and controls browser simulators.
vm.html
Implements dart:html in VM and Flutter. In browser, exports "dart:html". [...]
vm.indexed_db
Implements dart:indexed_db in VM and Flutter. In browser, exports "dart:indexed_db".
vm.js
Implements dart:js in VM and Flutter. In browser, exports "dart:js". [...]
vm.js_util
Implements dart:js_util in VM and Flutter. In browser, exports "dart:js_util". [...]
vm.svg
Implements dart:svg in VM and Flutter. In browser, exports "dart:svg".