Pub Package Github Actions CI

Introduction

A cross-platform dart:html:

  • Eases cross-platform development
    • You can use this package in browsers, mobile, and server-side.
    • Just replace dart:html imports with package:universal_html/html.dart. In browsers, dart:html will be automatically used.
  • Extensive support for handling HTML and XML documents
    • Parse, manipulate, and print DOM nodes.
    • Find DOM nodes with querySelectorAll and other CSS query methods.
    • Submit forms and more.

The project is licensed under the Apache License 2.0. Some of the source code was adopted from the original dart:html, which is documented in the relevant files.

Used by

Similar projects

Getting started

1. Add dependency

In pubspec.yaml:

dependencies:
  universal_html: ^1.2.1

2. Choose library

import 'package:universal_html/html.dart';

This library exports dart:html by default. You can also use import 'package:universal_html/prefer_sdk/html.dart';.

If you use this library, Dart tools may mistakenly think that your package is not compatible with VM/Flutter.

Option B

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

This library exports our implementation by default. The main advantage of this library is easier debugging. If you click "Go to declaration" in your IDE, you will see the implementation.

Getting warnings? In some cases, when you mix universal_io classes with dart:html classes, your IDE produces type warnings ("universal_html Element is not dart:html Element"). Your application should still compile (in browser, universal_html classes will be dart:html classes).

3. Use

import "package:universal_html/html.dart";

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

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

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

Implemented APIs

List of differences

DIFFERENCES.md contains a programmatically generated list of dart:html APIs missing from this package.

Summary

  • Document node classes
  • DOM parsing
    • Use element.innerHtml setter, DomParser, or package:universal_html/parsing.dart.
    • HTML parsing uses package:html, CSS parsing uses package:csslib, and XML parsing uses our own parser.
  • DOM printing
    • Use element.innerHtml or element.outerHtml.
  • DOM events
    • For example, element.onClick.listen(...) receives invocation of element.click().
  • CSS classes (CssStyleDeclaration, etc.)
  • Most CSS queries
  • window.history
  • Form submitting
  • EventSource ("application/event-stream" client)

Additional helpers

Parsing HTML / XML

We recommend that you use package:universal_html/parsing.dart (instead of DomParser):

import 'package:universal_html/parsing.dart';

void main() {
  // HTML
  final htmlDocument = parseHtmlDocument('<html>...</html>');

  // XML
  final xmlDocument = parseXmlDocument('<xml>...</xml>');
}

Server-side rendering

The package comes with ServerSideRenderer, which is a web server for rendering your web application in the server-side.

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!");
}

Browser simulators

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

Future main() async {
  // Construct a browser simulator.
  final driver = new HtmlDriver();

  // Open a web page.
  await driver.setDocumentFromUri(Uri.parse("https://news.ycombinator.com/"));

  // Select the top story using a CSS query
  final topStoryTitle = driver.document.querySelectorAll(".athing > .title").first.text;

  // Print result
  print("Top Hacker News story is: ${topStoryTitle}");
}

Libraries

universal_html
Cross-platform dart:html. [...]
universal_html.driver
API for controlling browser simulators.
universal_html.indexed_db
universal_html.js
universal_html.js_util
universal_html.parsing
Helpers for parsing HTML / XML.
universal_html.svg
universal_html.web_gl