29:null 2a:["$","title",null,{"children":"Upgrading to Notebooks 2.0 | Observable | Observable"}] 2f:T5f4,### Block cells Block cells are used in `ojs` for more elaborate definitions. They are characterized by curly braces (`{…}`) and a return statement to indicate the cell's value. Here is a typical example adapted from D3’s [_Bar chart_](https://observablehq.com/@d3/bar-chart/2): ```ojs chart = { const width = 960; const height = 500; const svg = d3.create("svg") .attr("width", width) .attr("height", height); return svg.node(); } ``` To convert this named block cell to vanilla JavaScript: delete the cell name (`chart`), assignment operator (`=`), and surrounding curly braces (`{` and `}`); then replace the return statement with a variable declaration and a call to [`display`](/d/96643af8378d5694#explicit-display) as desired. ```js const width = 960; const height = 500; const svg = d3.create("svg") .attr("width", width) .attr("height", height); const chart = display(svg.node()); ``` For an anonymous block cell, omit the variable declaration. To hide the display, omit the call to `display`; you can use an [inline expression](/d/96643af8378d5694#inline-expressions) (_e.g._, `$\{chart}`) to display the chart elsewhere. Note: to make the code easier to reuse, you can alternatively write the cell as a function: ```js function chart() { const width = 960; const height = 500; const svg = d3.create("svg") .attr("width", width) .attr("height", height); return svg.node(); } ``` then call `display(chart())` to display the chart anywhere on the page.30:T408,### Generators In notebooks 1.0, the `yield` operator turns any cell [into a generator](https://observablehq.com/documentation/cells/observable-javascript#cells-implicitly-iterate-over-generators). In vanilla JavaScript, the `yield` operator is only allowed within generator functions. Therefore in `js` cells you'll need to wrap a generator cell declaration with an [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE). So this: ```ojs foo = { for (let i = 0; i < 10; ++i) { yield i; } } ``` can be converted to: ```js const foo = (function* () { for (let i = 0; i < 10; ++i) { yield i; } })(); ``` Note: since variables are evaluated lazily, `foo` will only run if it is referenced by another code block. If you want to perform asynchronous side effects, consider using an animation loop and the [invalidation promise](/d/96643af8378d5694#invalidation) instead of a generator. If you need to use `await` with the generator, too, use `async function*` to declare an async generator function instead.31:[] 2d:{"id":"342634064e732825","slug":"upgrading-to-notebooks-2-0","title":"Upgrading to Notebooks 2.0","thumbnail":"16d761ad17a46124aaf66937ca017053ad4af01818e594ec84253910c9de4fea","access_level":"public","create_time":"$D2026-06-10T18:47:45.804Z","update_time":"$D2026-09-13T22:25:18.204Z","view_time":null,"first_public_time":"$D2026-06-12T18:07:53.079Z","has_unpublished_edits":null,"fork":false,"stars":9,"starred":false,"owner":{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024"},"version":382,"publish_version":382,"role":null,"authored":false,"authors":[{"type":"individual","id":"0bb2842b01e0c652","login":"tophtucker","name":"Toph Tucker","avatar_url":"https://avatars-next.observableusercontent.com/3706c31a8f9c59bb716c022c04b9c073144cd1368b78ac85f49139be6c93c34e","tier":null},{"type":"individual","id":"45a379fcfcb14253","login":"fil","name":"Fil","avatar_url":"https://avatars-next.observableusercontent.com/d5b1777907117a2bdf2a07eb98600d7a9beb21639fde42b9753e95c88c7731a6","tier":null},{"type":"individual","id":"074c414ad1d825f5","login":"mbostock","name":"Mike Bostock","avatar_url":"https://avatars-next.observableusercontent.com/7dbba99ced40bd5ab8013c99b1a11da61231bce321ba1148a9d16ad0f121550a","tier":null}],"members":[{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024","role":"editor"},{"type":"individual","id":"0bb2842b01e0c652","login":"tophtucker","name":"Toph Tucker","avatar_url":"https://avatars-next.observableusercontent.com/3706c31a8f9c59bb716c022c04b9c073144cd1368b78ac85f49139be6c93c34e","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":4,"collection":{"id":"24eb6ec5e74aa0c6","slug":"documentation","title":"Documentation","owner":{"id":"f35c755083683fe5","login":"observablehq","name":"Observable"}},"type":"notebook","body":{"title":"Upgrading to Notebooks 2.0","cells":[{"id":19,"value":"# Upgrading to Notebooks 2.0\n\nThe new Observable does its best to be backwards compatible with notebooks written in the old editor. With a few exceptions, notebooks should work as before. But if want to try updating your notebooks to take advantage of the [new system](https://new.observablehq.com/d/96643af8378d5694), this guide is for you.\n\nThere are two categories of changes to consider:\n1. [Upgrading the standard library](#upgrading-the-standard-library)\n2. [Using vanilla JavaScript](#using-vanilla-java-script)\n\nWe’ll cover them in turn. If you have questions, or find a compatibility issue, feel free to discuss on [the Observable forum](https://talk.observablehq.com/) — and remember the Observable Agent can also help you upgrade!","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":24,"value":"## Upgrading the standard library\n\nOpen the ${icon(\"dependencies\")} **Dependencies** panel from the right sidebar. The icon shows a red dot for notebooks using the 2018 standard library. You’ll see two options:\n\n- 2026\n- 2018 (deprecated)\n\nSelect _2026_ to immediately see how your notebook renders under the new standard library. In most notebooks everything works immediately. But you might notice some changes in the way Markdown, HTML and SVG are rendered, or code that ceases to work because it relies on a given version of a recommended library.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":25,"value":"### Markdown\n\nThe 2018 version of Markdown cells and `md` uses [marked](https://marked.js.org/). The 2026 version uses [markdown-it](https://github.com/markdown-it/markdown-it), which conforms to the [CommonMark specification](https://spec.commonmark.org/). Notably, CommonMark does not interpret Markdown syntax within HTML blocks; for example, `

This is **bold**.

` does _not_ render in bold and instead shows literal asterisks. [Typographic replacements](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs) are also enabled in 2026: straight quotes (`'`) are promoted to curly quotes (`’`), `--` becomes an en-dash (`–`), `...` becomes an ellipsis (…), _etc._","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":8,"value":"### html and svg\n\nIn the 2018 standard library, the `html` and `svg` tagged template literals simply concatenate HTML source. Hence, if you interpolate a string such as `

hello $\\{\"world\"}

`, the string is interpolated as HTML and the resulting output includes italics. This behavior is potentially surprising and unsafe when applied to arbitrary input. The 2026 standard library's `html` and `svg` in contrast are built on [Hypertext Literal](https://github.com/observablehq/htl), which automatically escapes interpolated values appropriately based on context, so an interpolated `\"world\"` renders literally as `world`. Note that HTML cells in the 2018 standard library already used Hypertext Literal (as `htl.html`), and hence their behavior is unchanged in the latest version.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":26,"value":"### require and resolve\n\nThe 2018 standard library predates the widespread adoption of [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), favoring [asynchronous module definitions (AMD)](https://github.com/d3/d3-require) for loading libraries via the `require()` function. The 2026 library instead favors standard ES modules and [import statements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). Before:\n```ojs\nd3 = require(\"d3\")\n```\n\nAfter:\n```js\nimport * as d3 from \"npm:d3\";\n```\n\nSee the [imports](./notebooks-2-0-system-guide#imports) section in the system guide for details. In the 2026 library, `require()` has been removed. While you can still import `d3-require` explicitly to use require, you are strongly encouraged to use standard imports.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":16,"value":"## Using vanilla JavaScript\n\nNotebooks 1.0 used an idiosyncratic JavaScript syntax called _Observable JavaScript_ or OJS. Notebooks 2.0 instead favor vanilla JavaScript and TypeScript syntax for better portability and interoperability.\n\nTo upgrade to `js`, there are three forms of `ojs` cell to consider and that require slightly different treatment. An Observable JavaScript cell can be an _expression cell_ consisting of a single JavaScript expression (such as `1 + 2`), a _block cell_ consisting of any number of JavaScript statements (such as `add(1, 2);`), or an _import cell_ importing another notebook.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":22,"value":"### Expression cells\n\nNamed expression cells in `ojs` can be converted into standard variable declarations, typically using `const`. So this:\n\n```ojs\nfoo = 42\n```\n\nbecomes this:\n\n```js\nconst foo = 42;\n```\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":17,"value":"Variable declarations in `js` cells don’t implicitly display. To display the value of a variable (such as `foo` above), call `display` explicitly. The `display` function returns its argument, so you can write:\n\n```js\nconst bar = display({hello: \"world\"});\n```\n\nJavaScript cells allow multiple variable declarations in the same code block, so you can coalesce multiple `ojs` cells from a notebook into a single `js` cell. But note that there’s no [implicit `await`](/d/96643af8378d5694#promises) when referring to a variable declared in the same code block --- so beware of promises.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5,"value":"$2f","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":27,"value":"### Imports\n\nObservable JavaScript cells can import another notebook like so:\n\n```ojs\nimport {BarChart} from \"@d3/bar-chart\"\n```\n\nThe vanilla JavaScript equivalent is a standard import declaration using the `observable:` protocol:\n\n```js\nimport {BarChart} from \"observable:@d3/bar-chart\";\n```\n\nAlternatively, you can use import attributes to declare an Observable import, allowing you to import reactive JavaScript from an arbitrary URL, including self-hosted notebooks:\n\n```js\nimport {BarChart} from \"https://api.observablehq.com/@d3/bar-chart.js?v=4\" with {type: \"observable\"};\n```\n\nNote: Observable JavaScript's [`import with` syntax](https://observablehq.com/documentation/notebooks/imports#import-with), which allows injecting symbols into the imported notebook, is deprecated. We recommend rewriting the imported notebook to export a standard function instead.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":18,"value":"$30","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6,"value":"### Views\n\nIn `ojs` cells, the nonstandard [`viewof` operator](https://observablehq.com/@observablehq/views) is used to declare a reactive value that is controlled by a user interface element such as a range input. In `js` cells, the `view` function performs the equivalent task with vanilla syntax. So this:\n\n```ojs\nviewof gain = Inputs.range([0, 11], {value: 5, step: 0.1, label: \"Gain\"})\n```\n\ncan be converted to:\n\n```js\nconst gain = view(Inputs.range([0, 11], {value: 5, step: 0.1, label: \"Gain\"}));\n```\n\nIn other words: replace `viewof` with `const`, and then wrap the input declaration with a call to `view`. The `view` function both displays the given input and returns the corresponding value generator so you can define a top-level reactive value.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":7,"value":"### Mutables\n\nIn `ojs` cells, the nonstandard [`mutable` operator](https://observablehq.com/@observablehq/mutable) is used to declare a reactive value that can be assigned from another cell. In vanilla `js`, the `Mutable` function performs the equivalent task, with an explicit setter function. So this:\n\n```ojs\nmutable foo = 42\n```\n\n```ojs\n{\n mutable foo = 0;\n}\n```\n\ncan be converted to:\n\n```js\nconst foo = Mutable(42);\nconst setFoo = (x) => (foo.value = x);\n```\n\n```js\nsetFoo(0);\n```\n\nNote that `setFoo` must be declared in the same code block as `foo`, and that outside of that block, `foo` represents the value; any code that depends on `foo` will update reactively after `setFoo` is invoked.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":32,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":31,"value":"import {keys, buttons} from \"observable:@observablehq/keys\";\nimport {icon} from \"observable:@observablehq/icons\";","pinned":true,"hidden":false,"mode":"ts","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W31","stdlib":"2","titling":"auto"}} 2e:"$2d:body"