Documentation
observablehq.com↗

Cells ​

Notebooks

All of Observable notebooks are made of cells. To build a notebook is to add cells to a notebook.

An Observable notebook split into different sections representing various cell types like Markdown (for text), inputs, and a chart. Text reads: Everything you see in an Observable notebook is made from cells.
A notebook divided into cells.

Cells can be added in a few different ways in Observable.

Add cell menu ​

To add a cell, click the + button on the left above or below any cell to open the add cell menu.

The Add cell menu opened up as it would be by default in a new notebook.
The add cell menu.

The most basic cell modes are JavaScript, Markdown, and HTML. The rest of the menu is divided into sections:

  • Data: add a SQL query, file attachment, etc.
  • Tables: display and transform data in tables
  • Plot: add Observable Plot snippets, from bars to box plots
  • Maps: visualize geographical data
  • Trees and Networks: show connections among nodes of a graph
  • Inputs: add controls like sliders and checkboxes
  • Text: add headings, lists, and images
  • Graphics: add custom D3, SVG, or Canvas
  • Notifications: send messages to Slack or email
  • Sample data: get started with convenient examples
  • Imports: import from notebooks or npm

Filtering the menu ​

Type to filter the menu to matching items insert the corresponding type of cell into your notebook.

The add cell menu, filtered to results containing “bar”
Filtering to just results containing the term “bar”, like bar charts.

If your filter does not match any known menu items, you can insert what you typed as a cell, search all of Observable for the term, or ask AI Assist.

The add cell menu, filtered to results containing “bar chart race”, of which there are none; the menu shows options to insert that text as a JavaScript, Markdown, or HTML cell, or search Observable (highlighted), or ask AI Assist
There are no items in the menu that match “bar chart race”, but you can search Observable for examples to fork.

Cell suggestions ​

The add cell menu will sometimes light up gold with contextual options to add a cell based on the cell above. Tabular data can be made into a table or chart; no-code data table cells can be converted to SQL code; and no-code chart cells can be converted to JavaScript code.

A data table cell with suggestions to “Create chart” or “Convert to SQL”
The Create chart button and Convert to SQL button.

Evaluating cells ​

To run a cell, click the Play button or press Shift-Return ⇧↩︎ . This updates the display of the cell above the editor, and runs any other cells that depend on it. The play button appears outlined if there are no changes to run, and filled-in if there are. Cells are implicitly run when you blur an editor, e.g. by pressing Esc ⎋ .

Naming cells ​

Naming cells allows you to refer to the cell elsewhere in a notebook, or import it to another notebook.

Name a JavaScript cell in one of four ways:

  • Name a cell expression:
js
expressionName = 8
  • Name a block:
js
blockName = {
  return 80;
}
  • Name a function declaration:
js
function functionName() {
  return 800;
}
  • Name a class:
js
class className {}

Name a Markdown cell by entering the name of the cell in the following area (visible at the bottom of your browser window when you are editing the cell):

Menu bar that appears in the bottom of the browser window when editing a Markdown cell, with a blank text box on the left where a user can enter a cell name.

For specialty cells like the Data Table, SQL and Chart cell, you can either edit the cell name from the menu in the bottom of the browser as shown above, or you can update the cell name in the top left of the cell:

Screen shot of a Data table cell, with a text box in the upper left reading 'addCellNameHere'.