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.
• svg - render SVG.
• 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:

DOM.canvas(960, 500)

This is equivalent to:

{
  let canvas = document.createElement("canvas");
  canvas.width = 960;
  canvas.height = 500;
  return canvas;
}

# 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:

{
  let context = DOM.context2d(960, 500);
  return context.canvas;
}

If the device pixel ratio is two, this is equivalent to:

{
  let canvas = document.createElement("canvas");
  canvas.width = 1920;
  canvas.height = 1000;
  canvas.style.width = "960px";
  let context = canvas.getContext("2d");
  context.scale(2, 2);
  return canvas;
}

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:

DOM.element("h1")

This is equivalent to:

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):

DOM.element("svg:svg")

This is equivalent to:

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:

DOM.input("file")

This is equivalent to:

{
  let input = document.createElement("input");
  input.type = "file";
  return input;
}

# 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:

DOM.range(-180, 180, 1)

This is equivalent to:

{
  let input = document.createElement("input");
  input.min = -180;
  input.max = 180;
  input.step = 1;
  input.type = "range";
  return input;
}

Or using html:

html`<input type=range min=-180 max=180 step=1>`

# 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:

DOM.select(["red", "green", "blue"])

This is equivalent to:

{
  let select = document.createElement("select");
  let optionRed = select.appendChild(document.createElement("option"));
  optionRed.value = optionRed.textContent = "red";
  let optionGreen = select.appendChild(document.createElement("option"));
  optionGreen.value = optionGreen.textContent = "green";
  let optionBlue = select.appendChild(document.createElement("option"));
  optionBlue.value = optionBlue.textContent = "blue";
  return select;
}

For greater control, consider using html instead. For example, here is an equivalent way to define the above drop-down menu:

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:

DOM.svg(960, 500)

This is equivalent to:

{
  let 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");
  return svg;
}

# DOM.text(string)

Returns a new text node with the specified string value. For example, to say hello:

DOM.text("Hello, world!")

This is equivalent to:

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:

{
  let 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])

Returns a promise that resolves with the specified value after the specified duration in milliseconds.

# 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 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!”:

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:

html`Hello, <b>world</b>!`

Is equivalent to this expression:

html`<div>Hello, <b>world</b>!</div>`

If an embedded expression is a DOM element, it is embedded in generated HTML. For example, to embed TeX within HTML:

html`I like ${tex`\KaTeX`} for math.`

If an embedded expression is an array, the elements of the array are embedded in the generated HTML. For example, to create a table from an array of values:

html`<table>
  <tbody>${["zero", "one", "two"].map((name, i) => html`<tr>
    <td>${name}</td><td>${i}</td>
  </tr>`)}</tbody>
</table>`

# svg(strings, values…)

Returns the SVG element represented by the specified strings and values. This function is intended to be used as a tagged template literal. For example, to create an SVG element whose content is a circle:

svg`<svg width=16 height=16>
  <circle cx=8 cy=8 r=4></circle>
</svg>`

If the resulting SVG fragment is not a single SVG element, is it wrapped in a G element. For example, this expression:

svg`
<circle cx=8 cy=4 r=4></circle>
<circle cx=8 cy=8 r=4></circle>
`

Is equivalent to this expression:

svg`<g>
  <circle cx=8 cy=4 r=4></circle>
  <circle cx=8 cy=8 r=4></circle>
</g>`

If an embedded expression is a DOM element, it is embedded in generated SVG. If an embedded expression is an array, the elements of the array are embedded in the generated SVG.

# md(strings, values…)

md`Hello, *world*!`

If an embedded expression is a DOM element, it is embedded in generated HTML. If an embedded expression is an array, the elements of the array are embedded in the generated HTML.

# 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("[email protected]").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.