To create responsive SVG, set the max-width to 100% and the height to auto:
jsIn general, you probably want to use the html or svg tagged template literal instead of DOM.svg.
# DOM.text (string ) <>
Returns a new text node with the specified string value. For example, to say hello:
js`This is equivalent to using the html tagged template literal:
jsHello, world!In general, you probably want to use the html tagged template literal instead of DOM.text.
# DOM.uid ([name ]) <>
Returns a new unique identifier . If name is specified, the identifier .id will be derived from the specified name , which may be useful for debugging. If DOM.uid is called repeatedly with the same name , every returned identifier is still unique (that is, different). Identifiers are useful in SVG: use identifier .href for IRI references, such as the xlink:href attribute; use identifier .toString for functional notation, such as the clip-path presentation attribute.
For example, to clip the Mona Lisa to a circle of radius 320px:
js;`The use of DOM.uid is strongly recommended over hand-coding as it ensures that your identifiers are still unique if your code is imported into another notebook. Because identifier .href and identifier .toString return absolute rather than local IRIs, it also works well in conjunction with a notebook’s base URL .
$3 See Reading Local Files for examples.
# Files.buffer (file ) <>
Reads the specified file , returning a promise of the ArrayBuffer yielded by fileReader .readAsArrayBuffer
# Files.text (file ) <>
Reads the specified file , returning a promise of the string yielded by fileReader .readAsText
# Files.url (file ) <>
Reads the specified file , returning a promise of the data URL yielded by fileReader .readAsDataURL
js`A data URL may be significantly less efficient than URL.createObjectURL method for large files. For example:
js`
$3 See File Attachments on Observable for examples.
# FileAttachment (name ) <>
Returns the file attachment with the given name , or throws an error if there is no file with the given name.
js`FileAttachments work similarly to the Fetch API , providing methods that return promises to the file’s contents in a handful of convenient forms.
# attachment .url () <>
Returns a promise to the URL at which the file may be retrieved.
js`# attachment .text () <>
Returns a promise to the file’s contents as a JavaScript string.
js`# attachment .json () <>
Returns a promise to the file’s contents, parsed as JSON into JavaScript values.
js`# attachment .csv ({array = false, typed = false} = {}) <>
Returns a promise to the file’s contents, parsed as comma-separated values (CSV) into an array.
js`If array is true, an array of arrays is returned; otherwise, the first row is assumed to be the header row and an array of objects is returned, and the returned array has a data .columns property that is an array of column names. (See d3.csvParseRows .) If typed is true, automatic type inference is applied; only use this feature if you know your data is compatible.
# attachment .tsv ({array = false, typed = false} = {}) <>
Returns a promise to the file’s contents, parsed as tab-separated values (TSV) into an array.
js`If array is true, an array of arrays is returned; otherwise, the first row is assumed to be the header row and an array of objects is returned, and the returned array has a data .columns property that is an array of column names. (See d3.tsvParseRows .) If typed is true, automatic type inference is applied to each row independently; if typed is “auto”, the type inference is based on a sample of rows. Only use this feature if you know your data is compatible.
# attachment .image (options ) <>
Returns a promise to a file loaded as an Image . The promise resolves when the image has finished loading, making this useful for reading the image pixels in Canvas, or for loading the image into a WebGL texture. Consider attachment .url
js`If desired, additional image properties can be passed in as options .
js`# attachment .arrayBuffer () <>
Returns a promise to the file’s contents as an ArrayBuffer .
js`# attachment .stream () <>
Returns a promise to a ReadableStream of the file’s contents.
js`# attachment .blob () <>
Returns a promise to a Blob containing the raw contents of the file.
js`# attachment .sqlite () <>
Returns a promise to the file loaded as a SQLite database client .
js`# attachment .xlsx () <>
Returns a promise to the file loaded as a Workbook .
js`# attachment .xml () <>
Returns a promise to an XMLDocument containing the contents of the file.
js`# attachment .html () <>
Returns a promise to an HTMLDocument containing the contents of the file.
js`# attachment .zip () <>
Returns a promise to a ZipArchive containing the contents of the file.
js`# FileAttachments (resolve ) <>
Note: this function is not part of the Observable standard library (in notebooks), but is provided by this module as a means for defining custom file attachment implementations when working directly with the Observable runtime.
Returns a FileAttachment resolve function. The resolve function is a function that takes a name and returns either an object {url, mimeType} representing the requested file if it exists, or null if the file does not exist. The url field (though not the object itself!) may be represented as a Promise if the URL is not yet known, such as for a file that is currently being uploaded. The mimeType must be a string, or undefined if the mime type is not known. For backwards compatibility, the resolve function may instead return just a URL, either a string or a promise.
#### Zip archives
# archive .filenames <>
Returns an array of paths representing the files contained within the archive.
js`# archive .file (path ) <>
Returns a file attachment for the file with the specified path . One of the file attachment methods can then be called to access the contents of the file. For example, to read a text file, use attachment .text
js`
$3 # Generators.disposable (value , dispose ) <>
Returns a new generator that yields the specified value exactly once. The generator .returndispose function, passing in the specified value . When this generator is the return value of a cell, this allows resources associated with the specified value to be disposed automatically when a cell is re-evaluated: generator .return is called by the Observable runtime on invalidation. For example, to define a cell that creates a self-disposing Tensor :
js`See also invalidation .
# Generators.filter (iterator , test ) <>
Returns a generator that yields a subset of values from the specified iterator , if and only if the specified test function returns truthy for the given value. The test function is invoked with the current value from the iterator and the current index, starting at 0 and increasing by one. For example, to yield only odd integers in [0, 100]:
js`This method assumes that the specified iterator is synchronous; if the iterator yields a promise, this method does not wait for the promise to resolve before continuing. If the specified iterator is a generator, this method also does not (currently) wrap the specified generator’s return and throw methods.
# Generators.input (input ) <>
Returns a new generator that yields promises to the current value of the specified input element; each promise resolves when the input element emits an event. (The promise resolves when the event is emitted, even if the value of the input is unchanged.) If the initial value of the input is not undefined, the returned generator’s first yielded value is a resolved promise with the initial value of the input .
The type of event that triggers promise resolution depends on the input .type as follows:
For button, submit and checkbox inputs, click* events. For file inputs, change* events. For all other types, input* events.
The resolved value is likewise dependent on the input .type as follows:
For range and number inputs, input*.valueAsNumber. For date inputs, input*.valueAsDate. For checkbox inputs, input*.checked. For single-file inputs ( input.multiple is falsey), input*.files[0]. For multi-file inputs ( input.multiple is truthy), input*.files. For all other types, input*.value.
The specified input need not be an HTMLInputElement, but it must support the target .addEventListener and target .removeEventListener methods of the EventTarget interface .
Generators.input is used by Observable’s viewof operator to define the current value of a view, and is based on Generators.observe . One often does not use Generators.input directly, but it can be used to define a generator cell exposing the current value of an input, and you can also read the yielded values by hand. For example, to accumulate the first four values:
js`Generators.input is lossy and may skip values: if more than one event is emitted before the next promise is pulled from the generator (more than once per animation frame), then the next promise returned by the generator will be resolved with the latest input value, potentially skipping intermediate values. See Generators.queue for a non-debouncing generator.
# Generators.map (iterator , transform ) <>
Returns a generator that yields transformed values from the specified iterator , applying the specified transform function to each value. The transform function is invoked with the current value from the iterator and the current index, starting at 0 and increasing by one. For example, to yield perfect squares:
js`This method assumes that the specified iterator is synchronous; if the iterator yields a promise, this method does not wait for the promise to resolve before continuing. If the specified iterator is a generator, this method also does not (currently) wrap the specified generator’s return and throw methods.
# Generators.observe (initialize ) <>
Returns a generator that yields promises to an observable value, adapting a push-based data source (such as an Observable , an EventEmitter or an EventTarget ) to a pull-based one.
The specified initialize function is invoked before Generators.observe returns, being passed a change function; calling change triggers the resolution of the current promise with the passed value. The initialize function may also return a dispose function; this function will be called when the generator is disposed . (See invalidation .)
For example, to observe the current value of a text input element, you might say:
js // An event listener to yield the element’s new value.
// Attach the event listener.
// Yield the element’s initial value.
// Detach the event listener when the generator is disposed.
`(See also Generators.input .)
Generators.observe is typically used to define a generator cell , but you can also read the yielded values by hand. For example, to accumulate the first four values:
js`Generators.observe is lossy and may skip values: if change is called more than once before the next promise is pulled from the generator (more than once per animation frame), then the next promise returned by the generator will be resolved with the latest value passed to change , potentially skipping intermediate values. See Generators.queue for a non-debouncing generator.
# Generators.queue (initialize ) <>
Returns a generator that yields promises to an observable value, adapting a push-based data source (such as an Observable , an EventEmitter or an EventTarget ) to a pull-based one. The specified initialize function is invoked before Generators.queue returns, being passed a change function; calling change triggers the resolution of the current promise with the passed value. The initialize function may also return a dispose function; this function will be called when the generator is disposed . (See invalidation .)
For example, to observe the value of a text input element, you might say:
js // An event listener to yield the element’s new value.
// Attach the event listener.
// Yield the element’s initial value.
// Detach the event listener when the generator is disposed.
`(See also Generators.input .)
Generators.queue is typically used to define a generator cell , but you can also read the yielded values by hand. For example, to accumulate the first four values:
js`Generators.queue is non-lossy and, as a result, may yield “stale” values: if change is called more than once before the next promise is pulled from the generator (more than once per animation frame), the passed values are queued in order and the generator will return resolved promises until the queue is empty again. See Generators.observe for a debouncing generator.
# Generators.range ([start , ]stop [, step ]) <>
Returns a generator yielding an arithmetic progression, similar to the Python built-in range . This method is often used to iterate over a sequence of uniformly-spaced numeric values, such as the indexes of an array or the ticks of a linear scale. (See also d3.range .)
For example, to iterator over the integers from 0 to 100:
js`Or more simply:
js`If step is omitted, it defaults to 1. If start is omitted, it defaults to 0. The stop value is exclusive; it is not included in the result. If step is positive, the last element is the largest start + i \ step less than stop; if step is negative, the last element is the smallest start + i \ step greater than stop . If the returned array would contain an infinite number of values, an empty range is returned.
The arguments are not required to be integers; however, the results are more predictable if they are. The values in the returned array are defined as start + i \ step, where i* is an integer from zero to the total number of elements in the returned array minus one. For example:
js`This unexpected behavior is due to IEEE 754 double-precision floating point, which defines 0.2 * 3 = 0.6000000000000001. Use d3-format to format numbers for human consumption with appropriate rounding.
Likewise, if the returned array should have a specific length, consider using array .map
js`
js`# Generators.valueAt (iterator , index ) <>
Returns the value from the specified iterator at the specified index . For example, to return the first element from the iterator:
js`This method assumes that the specified iterator is synchronous; if the iterator yields a promise, this method does not wait for the promise to resolve before continuing.
# Generators.worker (source ) <>
Returns a new disposable generator that yields a dedicated Worker running the specified JavaScript source . For example, to create a worker that echos messages sent to it:
js)`The worker will be automatically terminated when generator .return
$3 # Promises.delay (duration [, value ]) <>
Returns a promise that resolves with the specified value after the specified duration in milliseconds. For example, to define a cell that increments approximately every second:
js`If you desire precise synchronization, such as a timer that ticks exactly every second, use Promises.tick instead of Promises.delay.
# 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. For example, to define a cell that increments every second, on the second:
js`Or, as an async generator:
js`# Promises.when (date [, value ]) <>
Returns a promise that resolves with the specified value at the specified date . This method relies on setTimeout , and thus the specified date must be no longer than 2,147,483,647 milliseconds (24.9 days) from now.
$3 # invalidation
A promise that resolves when the current cell is re-evaluated: when the cell’s code changes, when it is run using Shift-Enter, or when a referenced input changes. This promise is typically used to dispose of resources that were allocated by the cell. For example, to abort a fetch if the cell is invalidated:
js`The invalidation promise is provided by the runtime rather than the standard library because it resolves to a new promise each time a cell is evaluated. See also Generators.disposable .
# now <>
The current value of Date.now . For example, to display the current time in Markdown:
jsThe current time is: ${new Date(now).toISOString()}# width <>
The current width of cells. For example, to make a rounded rectangle in SVG that resizes to fit the page:
js# visibility ([value ]) <>
Returns a promise that resolves with the specified value when this cell is visible in the viewport. The visibility function is provided by the runtime rather than the standard library because it resolves to a different function for each cell.
$3 # html \
string \ <> Returns the HTML element represented by the specified HTML string literal. This function is intended to be used as a tagged template literal . Leading and trailing whitespace is automatically trimmed. For example, to create an H1 element whose content is “Hello, world!”:
`jsHello, world!If the resulting HTML fragment is not a single HTML element or node, is it wrapped in a DIV element. For example, this expression:
jsHello, world !Is equivalent to this expression:
js Hello, world !
If an embedded expression is a DOM element, it is embedded in generated HTML. For example, to embed TeX within HTML:
jsI 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:
js${["zero", "one", "two"].map((name, i) => html${name} ${i}
# svg \
string \ <> Returns the SVG element represented by the specified SVG string literal. This function is intended to be used as a tagged template literal . Leading and trailing whitespace is automatically trimmed. For example, to create an SVG element whose content is a circle:
`jsIf the resulting SVG fragment is not a single SVG element, is it wrapped in a G element. For example, this expression:
jsIs equivalent to this expression:
jsIf 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.
$3 # md \
string \ <> Returns the HTML element represented by the specified Markdown string literal. Implemented by Marked . Leading and trailing whitespace is automatically trimmed. For example, to create an H1 element whose content is “Hello, world!”:
`js# Hello, world!If an embedded expression is a DOM element, it is embedded in generated HTML. For example, to embed LaTeX within Markdown:
jsMy favorite number is ${tex\tau}.If an embedded expression is an array, the elements of the array are embedded in the generated HTML. The elements may either be strings, which are interpreted as Markdown, or DOM elements. For example, given an array of data:
js`To create a table:
js
$3 # tex \
string \ <> Returns the HTML element represented by the specified LaTeX string literal. Implemented by KaTeX .
`jsE = mc^2# tex.block \
string \ <> Equivalent to tex , but uses KaTeX’s display mode to produce a bigger block element rather than a smaller inline element.
`jsE = mc^2# tex.options (options ) <>
Returns a function equivalent to tex , but with the specified options .
jsE = mc^2
$3 # require (names… ) <>
Returns a promise of the asynchronous module definition (AMD) with the specified names , loaded from npm. 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 :
`js`Or, to load d3-array and d3-color and merge them into a single object:
js`Or, to load d3-array 1.1.x:
js`See d3-require for more information.
# require.resolve (name ) <>
Returns a promise to the resolved URL to require the module with the specified name . For example:
js`# require.alias (aliases ) <>
Returns a require function with the specified aliases . For each key in the specified aliases object, any require of that key is substituted with the corresponding value. For example:
js`js`js`Equivalently:
js`Then to require the libraries:
js`js`js`
Installing The Observable standard library is built-in to Observable, so you don’t normally need to install or instantiate it directly. If you use NPM,
.# Library ([resolve ]) <>
Returns a new standard library object. If a resolve function is specified, it is a function that returns a promise to the URL of the module with the specified name ; this is used internally by require (and by extension, md and tex ). See d3-require for details.
For example, to create the default standard library, and then use it to create a canvas :
`js``The properties on the returned library instance correspond to the symbols (documented above) that are available in Observable notebooks. However, note that the library fields (such as library .now) are definitions , not values: the values may be wrapped in a function which, when invoked, returns the corresponding value.
# Library.resolve (name [, base ]) <>
An alias for d3.require.resolve .