41:null 42:["$","title",null,{"children":"Introducing Visual Dataflow | a-k | Observable"}] 48:T6e5,md`When I tried to write my first notebook in Observable, I was intrigued and confused. I knew there was some “magic” going on: things automatically updated when other things changed. The trouble was, which things and which things? I expected some things to automatically update and they didn’t. And I expected other things to stick around like normal, but instead they got wiped away by automatic updates I hadn’t expected. I was fighting the grain of the tool. It took a while to figure out what was going on; only then did Observable become my favorite coding environment. “Magic” is touted proudly on our homepage (_“Observable is the magic notebook for exploring data and thinking with code”_), but it can also be a pejorative term. We want Observable to be “magic” as in, like, remarkably effective; we don’t want it to be obscure! So, when I started working here in January, I was glad to find this issue already atop our priorities for the new year. We had to make the way code runs self-evident. You can see the first pieces of that now with what we call **Visual Dataflow**. A notebook is made of cells; those cells can be named; those names can be referenced as variables. When a cell yields a new value, anything that references its name will be re-evaluated. That makes those variables “reactive”, different from normal JavaScript variables. But they used to look the same. Now, we are explicitly showing reactive connections, both in the code editor and in a new minimap. If your screen is wide enough, we can demonstrate with this notebook itself. ${!widescreen ? "(It looks like it’s not, but there are plenty of screenshots below.)" : ""} Let’s define a cell that increments once a second and name it \`counter\`:`49:T4cb,md`In that code, see how \`counter\` has that special blue underline? That means it’s a reference to another cell. If \`counter\` changes, the whole cell above will automatically re-evaluate, as you can see by the flash of gray in the left margin and in the minimap every second. The blue-underline cell references can take you to their definitions: press ${key((mac ? `⌘cmd` : `ctrl`) + " j")} while the cursor is in the name, or hold ${key(mac ? `⌥opt` : `alt`)} and double-click it. ${await aside(FileAttachment("counter-sentence-focused.gif"))}When your cursor is in the \`counter\` cell, look again at the minimap. The circle labeled \`counter\` is now highlighted; more importantly, its connections are highlighted. There is a line going out of \`counter\` and into \`sentence\` like a wire. Data flows from left to right. We emphasize left-to-right in the minimap to highlight that data does _not_ necessarily flow top to bottom in a notebook. A definition can easily be below a reference to it; cells will run the same way no matter what order you arrange them in the notebook. This is unlike most programming environments — except for spreadsheets, where reactivity is so natural that nobody talks about it.`4a:T69d,gifs = gallery([ [ FileAttachment("Screen Shot 2020-04-10 at 2.47.51 AM.png"), md`The cell \`scale\` is focused; it refers to \`data\`, and \`chart\` refers to it` ], [ FileAttachment("rearrange.gif"), md`Reordering cells does not change inputs or outputs` ], [ FileAttachment("Screen Shot 2020-03-24 at 12.22.16 AM.png"), md`This import is used three times in this notebook` ], [ FileAttachment("Screen Shot 2020-03-24 at 12.40.17 AM.png"), md`\`barChart\` is focused and indirectly depends on \`data\`` ], [ FileAttachment("Screen Shot 2020-03-24 at 12.39.51 AM@1.png"), md`\`data\` is focused and indirectly affects \`barChart\`` ], [ FileAttachment("Screen Shot 2020-03-24 at 12.23.51 AM.png"), md`There is a circular definition error` ], [ FileAttachment("counter-indirect@1.gif"), md`Every cell to the right re-runs when \`counter\` runs` ], [ FileAttachment("keyframe-chart-update.gif"), md`This cell is calling \`chart.update\` but _won’t_ re-run \`chart\`` ], [ FileAttachment("Screen Shot 2020-04-09 at 2.00.52 AM.png"), md`Cells without names or references appear smaller` ], [ FileAttachment("Screen Shot 2020-04-09 at 2.08.52 AM.png"), md`When comparing a fork, changes are marked` ], [ FileAttachment("visual-mode v2.gif"), md`Select, move, pin, and delete multiple cells with [keyboard shortcuts](https://observablehq.com/@observablehq/cell-shortcuts)` ], [ FileAttachment("opt-tab.gif"), md`You can switch cells with ${key(mac ? "⌥opt ⇥tab" : "alt shift down")} and ${key(mac ? "⌥opt ⇧shift ⇥tab" : "alt shift up")}` ] ])4b:T50e,md`This is the result of a design process that involved every person at Observable. [Mike](https://observablehq.com/@mbostock) laid out the challenge and prototyped several ways of wiring cells together; [Toph](https://observablehq.com/@tophtucker) replied with a minimap idea; [Sydney](https://observablehq.com/@sydneypalumbo) focused the design and made it fast; [Dunstan](https://observablehq.com/@dunstan) found the ways it broke; [Jeremy](https://observablehq.com/@jashkenas) made it all work with the compiler. Others gave feedback in design reviews and at our last meetup. Along the way we refined some of our guiding principles, and dropped others. We tried to make it fast, clear, and stable — not comprehensive. Now we need your help. This work is supposed to help first-time users understand how their code is running, and to help you understand a complex notebook you’re seeing for the first time. If I’d had it when I started using Observable, I think I’d have figured a few things out a lot faster. But you can test that better than we ever could. So look at a [tricky notebook](https://observablehq.com/@d3/bar-chart-race-explained), start [one of your own](https://observablehq.com/new), and join the [forum](https://talk.observablehq.com/t/visual-dataflow/2976). ---`4c:[{"id":"1848dda6f518678f0e74282ab288d545d73a9a59adf8bcefa4359082cda3432c5f24de4078bba4a0f7875cb11691a29175a5d2f87dd6309f0fe8e931f27010fe","href":"https://static.observableusercontent.com/files/1848dda6f518678f0e74282ab288d545d73a9a59adf8bcefa4359082cda3432c5f24de4078bba4a0f7875cb11691a29175a5d2f87dd6309f0fe8e931f27010fe","name":"counter-indirect@1.gif","type":"image/gif","lastModified":1585109494006.409,"size":8664},{"id":"d4f43ea2437b8c7ed8920c71c61fc48b4de9b8332b7c73cf98f081216cd9a1544d193190393fc1112144d701962c3b9c50d686622b658ce22d9aee95f78d1fce","href":"https://static.observableusercontent.com/files/d4f43ea2437b8c7ed8920c71c61fc48b4de9b8332b7c73cf98f081216cd9a1544d193190393fc1112144d701962c3b9c50d686622b658ce22d9aee95f78d1fce","name":"counter-sentence-focused.gif","type":"image/gif","lastModified":1585109494006.409,"size":7508},{"id":"ce3f928ea92b53bb0785aba262152852aa8f832522a2ddf18911af7410ca9a98242fce0ddaa0291341946f290159b6af08994a7fdf3338bb6a74c0f51c3e0968","href":"https://static.observableusercontent.com/files/ce3f928ea92b53bb0785aba262152852aa8f832522a2ddf18911af7410ca9a98242fce0ddaa0291341946f290159b6af08994a7fdf3338bb6a74c0f51c3e0968","name":"Screen Shot 2020-03-24 at 12.22.16 AM.png","type":"image/png","lastModified":1585109494006.409,"size":13916},{"id":"44e3be19ed5824e2777e5fc3d4a633658de8444cfe148fa9e90f6c0e8368711e70a060f0c748e41139854fbddca086bc5787a54ed10e9865a5d2ed46eafbc095","href":"https://static.observableusercontent.com/files/44e3be19ed5824e2777e5fc3d4a633658de8444cfe148fa9e90f6c0e8368711e70a060f0c748e41139854fbddca086bc5787a54ed10e9865a5d2ed46eafbc095","name":"Screen Shot 2020-03-24 at 12.23.51 AM.png","type":"image/png","lastModified":1585109494006.409,"size":11952},{"id":"298023414fc1dd92bbdc750742df39e73a471f0499f6b69d9a8dfe2f014420119c9f30c728103d02a373c3e625cd8f9535b11ac460d629536990aef27822f024","href":"https://static.observableusercontent.com/files/298023414fc1dd92bbdc750742df39e73a471f0499f6b69d9a8dfe2f014420119c9f30c728103d02a373c3e625cd8f9535b11ac460d629536990aef27822f024","name":"Screen Shot 2020-03-24 at 12.39.51 AM@1.png","type":"image/png","lastModified":1585109494006.409,"size":13643},{"id":"22ccfc599fabd64ec24d218713b623df902acc66968b508526ab97ffde4c6872df68f525bb0e91edd92e1ff59660deaccce061d238b99ba9a76e5088e86d50e8","href":"https://static.observableusercontent.com/files/22ccfc599fabd64ec24d218713b623df902acc66968b508526ab97ffde4c6872df68f525bb0e91edd92e1ff59660deaccce061d238b99ba9a76e5088e86d50e8","name":"counter-sentence-unfocused.gif","type":"image/gif","lastModified":1585109494006.409,"size":6899},{"id":"1a99b4474aceafb15c911b5ac0a03c04ea4d0a51327f9d5a8649bdf753919d8141e0667c58072c2eddd716de8076974e64b64e34be0c7d0c591425115560be59","href":"https://static.observableusercontent.com/files/1a99b4474aceafb15c911b5ac0a03c04ea4d0a51327f9d5a8649bdf753919d8141e0667c58072c2eddd716de8076974e64b64e34be0c7d0c591425115560be59","name":"keyframe-chart-update.gif","type":"image/gif","lastModified":1585109494006.409,"size":7253},{"id":"e28e23273d03f7b576c8a312b8bc4ac2364487e86bee3daa97d10b87123a6f62c8e6aa416e7cbe9b5d6b221a0208be8a85c36e84a6f48501ae9befa1062f9ab5","href":"https://static.observableusercontent.com/files/e28e23273d03f7b576c8a312b8bc4ac2364487e86bee3daa97d10b87123a6f62c8e6aa416e7cbe9b5d6b221a0208be8a85c36e84a6f48501ae9befa1062f9ab5","name":"opt-tab.gif","type":"image/gif","lastModified":1585109494006.409,"size":126559},{"id":"d1fc37f1ed7087bb2b4d808eeae827d3d1a275f422e237b114ec85cc6d5a89dd46fa6c6d1350cb2f7d05e7213ec65f552c24b8ec5ed47d0548cb5a56e165a2eb","href":"https://static.observableusercontent.com/files/d1fc37f1ed7087bb2b4d808eeae827d3d1a275f422e237b114ec85cc6d5a89dd46fa6c6d1350cb2f7d05e7213ec65f552c24b8ec5ed47d0548cb5a56e165a2eb","name":"rearrange.gif","type":"image/gif","lastModified":1585109494006.409,"size":42866},{"id":"ca1567c6a23d31d98d4fc64bbe75c956479df503726dd034849b54be90d57cc12e0f4e19a4781f3427abe3b2430eaeaa196f95a1b06f2eaf7f9ec5e8e57d509a","href":"https://static.observableusercontent.com/files/ca1567c6a23d31d98d4fc64bbe75c956479df503726dd034849b54be90d57cc12e0f4e19a4781f3427abe3b2430eaeaa196f95a1b06f2eaf7f9ec5e8e57d509a","name":"Screen Shot 2020-03-24 at 12.40.17 AM.png","type":"image/png","lastModified":1585109494006.409,"size":13813},{"id":"f3c5ef5e1f7a2c556abf3847a3ff8b6ea9367a64a45af289c28ed216385452e2f81877c371b42706a6fbc9391f2432de000b1e5982965e5860a453dbe62c20c0","href":"https://static.observableusercontent.com/files/f3c5ef5e1f7a2c556abf3847a3ff8b6ea9367a64a45af289c28ed216385452e2f81877c371b42706a6fbc9391f2432de000b1e5982965e5860a453dbe62c20c0","name":"Screen Shot 2020-04-09 at 2.00.52 AM.png","type":"image/png","lastModified":1586412409915.868,"size":9483},{"id":"80ee53a2a1befc59c6c6f46bc873fb5c6f9261f227746bc604b51aabba9ab0d2fa9320c386012c758c36563de93442476f2de79c6916f2e82458b27a9ace4a38","href":"https://static.observableusercontent.com/files/80ee53a2a1befc59c6c6f46bc873fb5c6f9261f227746bc604b51aabba9ab0d2fa9320c386012c758c36563de93442476f2de79c6916f2e82458b27a9ace4a38","name":"Screen Shot 2020-04-09 at 2.08.52 AM.png","type":"image/png","lastModified":1586412544864.587,"size":12704},{"id":"26abc59fce8df333cf5df97eb801df06e51700a6e948b8349443ca2ab4f8477a6312365b7dbd67fee5259bc635b66ea42d0b880e4e58b3495acbcf669e4fbde9","href":"https://static.observableusercontent.com/files/26abc59fce8df333cf5df97eb801df06e51700a6e948b8349443ca2ab4f8477a6312365b7dbd67fee5259bc635b66ea42d0b880e4e58b3495acbcf669e4fbde9","name":"Screen Shot 2020-04-10 at 2.47.51 AM.png","type":"image/png","lastModified":1586501341205.537,"size":12584},{"id":"067a1921dd83259044f7bb06f4d9a774584d6e3ebc7acfb72b7801d267594c77f79fb2e3dce887cfb949ca593ff456b56c95745069b51bf8b10f0142d8f5123e","href":"https://static.observableusercontent.com/files/067a1921dd83259044f7bb06f4d9a774584d6e3ebc7acfb72b7801d267594c77f79fb2e3dce887cfb949ca593ff456b56c95745069b51bf8b10f0142d8f5123e","name":"slider-x.gif","type":"image/gif","lastModified":1585109494006.409,"size":8556},{"id":"0d03711dae86e274cff603b52de1566de8f16741fbb1830c6dd80fa89da62fc6a716044e1df0cd3ffb536edc7423ee860585c4b7269c44279eb030560ab2f5c5","href":"https://static.observableusercontent.com/files/0d03711dae86e274cff603b52de1566de8f16741fbb1830c6dd80fa89da62fc6a716044e1df0cd3ffb536edc7423ee860585c4b7269c44279eb030560ab2f5c5","name":"visual-mode v2.gif","type":"image/gif","lastModified":1586885209381.367,"size":55020}] 46:{"id":"c20e49a5c3253920","slug":"introducing-visual-dataflow","title":"Introducing Visual Dataflow","thumbnail":"f9cadb0718da909287d047b0dd655ff4683ea50181f4f762b98cb9b58f64fdb7","access_level":"public","create_time":"$D2026-08-17T15:41:36.570Z","update_time":"$D2026-08-17T15:41:42.917Z","view_time":null,"first_public_time":"$D2026-08-17T15:41:50.966Z","has_unpublished_edits":null,"fork":{"id":"07a0eaa84e6ce4a6","slug":"introducing-visual-dataflow","title":"Introducing Visual Dataflow","owner":{"id":"f35c755083683fe5","login":"observablehq","name":"Observable"}},"stars":1,"starred":false,"owner":{"type":"team","id":"0d89ff0d43911832","login":"a-kyselova","name":"a-k","avatar_url":"https://avatars-next.observableusercontent.com/c17731a6346b5dfce53e427b1b871e127393f84a1789e18931f02dc51f940fcc","tier":"starter_2024","bio":"","following":false},"version":872,"publish_version":872,"role":null,"authored":false,"authors":[{"type":"individual","id":"4abdd3c5ac6f602a","login":"akyselova","name":"Anastasiia","avatar_url":"https://avatars-next.observableusercontent.com/f400c814810bb16bc0121a8537885d2f84ff777dc43a704664ad27987b43d9df","tier":null,"bio":"","following":false}],"members":[{"type":"team","id":"0d89ff0d43911832","login":"a-kyselova","name":"a-k","avatar_url":"https://avatars-next.observableusercontent.com/c17731a6346b5dfce53e427b1b871e127393f84a1789e18931f02dc51f940fcc","tier":"starter_2024","role":"editor"}],"comments":[],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"titling":"auto","title":"Introducing Visual Dataflow","cells":[{"id":188,"value":"title = md`# Introducing Visual Dataflow`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":847,"value":"classicVsNextVisualDataflow","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":0,"value":"$48","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":6,"value":"counter = {\n let i = 0;\n while (true) {\n await Promises.delay(1000);\n yield i++;\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":27,"value":"md`${await aside(FileAttachment(\"counter-sentence-unfocused.gif\"))}Now look over at the upper right corner ↗ of this page. The little gray dots are the minimap. Mouse over it to expand names, and look for our \\`counter\\`. There it is! The third dot from the top is labeled \\`counter\\`. That represents the third cell in the notebook, the code above. It’s blinking, subtly, each time it runs.\n\nWe can take advantage of reactivity by referencing our \\`counter\\` in another cell:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":34,"value":"sentence = `${counter * 1000} milliseconds since you loaded the page.`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":39,"value":"$49","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":108,"value":"md`To illustrate: the slider below currently has a value of **${slider}**; as you move it, the data flows into _this_ cell, even though it’s _above_ the slider. But if you select either this cell or the slider cell, you can see in the minimap that data is still flowing _left to right_.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":100,"value":"viewof slider = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":157,"value":"md`${await aside(FileAttachment(\"slider-x.gif\"))}This is most satisfying and clarifying when you’re writing the code yourself. Un-comment the reference in the next line and run the cell to see the reference get highlighted and the wire plugged in:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":160,"value":"x = 2 // ** slider","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":585,"value":"md`The design of the minimap is deliberately restrained: it only lights up when you express the intent to edit by focusing a cell, and it only highlights the directly connected cells. It can’t show you the entire dependency graph at once, although [Mike](https://observablehq.com/@observablehq/notebook-visualizer) and [Tom](https://observablehq.com/@observablehq/notebook-visualizer-elk-edition) have notebooks that can. It’s also not a table of contents of headings in your document, although Mike has a [notebook for that, too](https://observablehq.com/@mbostock/toc). We’re still thinking about that sort of thing, and we have notebooks full of ideas. But first, we wanted something unobtrusive enough that it can sit ambiently in the corner — where a new user can see it without toggling any hidden option, and an experienced user can ignore it in their peripheral vision.`\n\n","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":491,"value":"md`Though sometimes subtle, the minimap can tell you a lot:\n\n\n\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":703,"value":"$4a","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":114,"value":"$4b","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":803,"value":"appendix = md`## Appendix`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":441,"value":"mac = /Mac|iPhone/.test(navigator.platform)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":445,"value":"widescreen = width >= 954","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":632,"value":"key = keys => html`${keys.split(\" \").map(key => `${key}`).join(\"\")}`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":666,"value":"aside = async file => html`

\n ${await Promise.all(items.map(async ([file, caption]) => html`

\n ${caption}\n

`))}\n

`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":844,"value":"import {classicVsNextVisualDataflow} from \"@observablehq/classic-vs-next-infobox\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W4c","stdlib":"2"}} 47:"$46:body"