The Observable notebook standard library.
If you use NPM, npm install @observablehq/notebook-stdlib
.
# runtimeLibrary([resolve])
Returns a new standard library object, defining the following properties:
- DOM - create HTML and SVG elements.
- Files - read local files into memory.
- Generators - utilities for generators and iterators.
- Promises - utilities for promises.
- require - load third-party libraries.
- html - render HTML.
- md - render Markdown.
- tex - render TeX.
- now - the current value of Date.now.
- width - the current page width.
If resolve is specified, it is a function that returns the URL of the module with the specified name; this is used internally by require.
# DOM.canvas(width, height)
Returns a new canvas element with the specified width and height. For example, to create a 960×500 canvas:
var canvas = DOM.canvas(960, 500);
This is equivalent to:
var canvas = document.createElement("canvas");
canvas.width = 960;
canvas.height = 500;
# DOM.context2d(width, height[, dpi])
Returns a new canvas context with the specified width and height and the specified device pixel ratio dpi. If dpi is not specified, it defaults to window.devicePixelRatio. For example, to create a 960×500 canvas:
var context = DOM.context2d(960, 500);
If the device pixel ratio is two, this is equivalent to:
var canvas = document.createElement("canvas");
canvas.width = 1920;
canvas.height = 1000;
canvas.style.width = "960px";
var context = canvas.getContext("2d");
context.scale(2, 2);
To access the context’s canvas, use context.canvas.
# DOM.download(object[, name][, value])
Returns an anchor element containing a button that when clicked will download a file representing the specified object. The object should be anything supported by URL.createObjectURL such as a file or a blob.
# DOM.element(name[, attributes])
Returns a new element with the specified name. For example, to create an empty H1 element:
var h1 = DOM.element("h1");
This is equivalent to:
var h1 = document.createElement("h1");
If the name has the prefix svg:
, math:
or xhtml:
, uses document.createElementNS instead of document.createElement. For example, to create an empty SVG element (see also DOM.svg):
var svg = DOM.element("svg:svg");
This is equivalent to:
var svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
If attributes is specified, sets any attributes in the specified object before returning the new element.
# DOM.input([type])
Returns a new input element with the specified type. If type is not specified or null, a text input is created. For example, to create a new file input:
var input = DOM.input("file");
This is equivalent to:
var input = document.createElement("input");
input.type = "file";
# DOM.range([min, ][max][, step])
Returns a new range input element. (See also DOM.input.) If max is specified, sets the maximum value of the range to the specified number; if max is not specified or null, sets the maximum value of the range to 1. If min is specified, sets the minimum value of the range to the specified number; if min is not specified or null, sets the minimum value of the range to 0. If step is specified, sets the step value of the range to the specified number; if step is not specified or null, sets the step value of the range to any
. For example, to create a slider that ranges the integers from -180 to +180, inclusive:
var input = DOM.range(-180, 180, 1);
This is equivalent to:
var input = document.createElement("input");
input.min = -180;
input.max = 180;
input.step = 1;
input.type = "range";
# DOM.select(values)
Returns a new select element with an option for each string in the specified values array. For example, to create a drop-down menu of three colors:
var select = DOM.select(["red", "green", "blue"]);
This is equivalent to:
var select = document.createElement("select");
var optionRed = select.appendChild(document.createElement("option"));
optionRed.value = optionRed.textContent = "red";
var optionGreen = select.appendChild(document.createElement("option"));
optionGreen.value = optionGreen.textContent = "green";
var optionBlue = select.appendChild(document.createElement("option"));
optionBlue.value = optionBlue.textContent = "blue";
For greater control, consider using html instead. For example, here is an equivalent way to define the above drop-down menu:
var select = html`<select>
<option value="red">red</option>
<option value="green">green</option>
<option value="blue">blue</option>
</select>`;
# DOM.svg(width, height)
Returns a new SVG element with the specified width and height. For example, to create a 960×500 blank SVG:
var svg = DOM.svg(960, 500);
This is equivalent to:
var svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
set.setAttribute("viewBox", "0,0,960,500")
svg.setAttribute("width", "960");
svg.setAttribute("height", "500");
# DOM.text(string)
Returns a new text node with the specified string value. For example, to say hello:
var hello = DOM.text("Hello, world!");
This is equivalent to:
var hello = document.createTextNode("Hello, world!");
# Files.buffer(file)
Reads the specified file, returning a promise of the ArrayBuffer yielded by fileReader.readAsArrayBuffer. This is useful for reading binary files, such as shapefiles and ZIP archives.
# Files.text(file)
Reads the specified file, returning a promise of the string yielded by fileReader.readAsText. This is useful for reading text files, such as plain text, CSV, Markdown and HTML.
# Files.url(file)
Reads the specified file, returning a promise of the data URL yielded by fileReader.readAsDataURL. This is useful for reading a file into memory, represented as a data URL. For example, to display a local file as an image:
Files.url(file).then(url => {
var image = new Image;
image.src = url;
return image;
})
However, note that it may be more efficient to use the synchronous URL.createObjectURL method instead, such as:
var image = new Image;
image.src = URL.createObjectURL(file);
return image;
# Generators.filter(iterator, test)
…
# Generators.input(input)
…
# Generators.map(iterator, transform)
…
# Generators.observe(initialize)
…
# Generators.queue(initialize)
…
# Generators.range([start, ]stop[, step])
…
# Generators.valueAt(iterator, index)
…
# Promises.delay(duration[, value])
…
# Promises.never
A promise that never resolves. Equivalent to new Promise(() => {})
.
# Promises.tick(duration[, value])
Returns a promise that resolves with the specified value at the next integer multiple of milliseconds since the UNIX epoch. This is much like Promises.delay, except it allows promises to be synchronized.
# Promises.when(date[, value])
… Note: the current implementation relies on setTimeout, and thus the specified date must be no longer than 2,147,483,647 milliseconds (24.9 days) from now.
# now
The current value of Date.now.
# width
The current width of cells.
# html(strings, values…)
Returns the HTML element or node represented by the specified strings and values. This function is intended to be used as a tagged template literal. For example, to create an H1 element whose content is “Hello, world!”:
var hello = html`<h1>Hello, world!</h1>`;
If the resulting HTML fragment is not a single HTML element or node, is it wrapped in a DIV element. For example, this expression:
var hello = html`Hello, <b>world</b>!`;
Is equivalent to this expression:
var hello = html`<div>Hello, <b>world</b>!</div>`;
# md(strings, values…)
var hello = md`Hello, *world*!`;
# tex(strings, values…)
tex`E = mc^2`
# tex.block(strings, values…)
Equivalent to tex, but uses KaTeX’s display mode to produce a bigger block element rather than a smaller inline element.
tex.block`E = mc^2`
# require(names…)
Returns a promise of the asynchronous module definition (AMD) with the specified names, loaded from unpkg. Each module name can be a package (or scoped package) name optionally followed by the at sign (@
) and a semver range. For example, to load d3-array:
require("d3-array").then(d3 => {
console.log(d3.range(100));
});
Or, to load d3-array and d3-color and merge them into a single object:
require("d3-array", "d3-color").then(d3 => {
console.log(d3.range(360).map(h => d3.hsl(h, 1, 0.5)));
});
Or, to load d3-array 1.1.x:
require("d3-array@1.1").then(d3 => {
console.log(d3.range(100));
});
See d3-require for more information.
# resolve(name)
Returns the resolved URL to require the module with the specified name.