Cell Options Reference

Introduction

This page details the available cell options in Quarto Live for interactive code blocks. You can use these options to control how your code is executed and displayed in your documents. Below, each option is explained along with concise examples for both R (using webr) and Python (using pyodide). For additional details, please refer to our comprehensive documentation.

Overview

Below is detailed reference information for these options.

General Options

Option	Default	Description
autorun	false	Automatically run the code block as soon as the engine loads.
edit	true	Determines if the code cell is editable.
runbutton	true	Displays the “Run Code” button if set to true; setting to false triggers immediate execution.
completion	true	Enables context-aware autocomplete suggestions in the editor.
include	true	Displays both the source code and its output in the final document.
persist	false	Saves code changes in the browser’s local storage so they persist on reload.
startover	true	Shows the “Start Over” button to reset the code to its original contents.
timelimit	30	Sets a time limit (in seconds) for code execution. Set to 0 to disable the limit.
min-lines	0	Minimum number of lines the editor should display.
max-lines	Infinity	Maximum number of lines the editor displays before scrolling becomes enabled.

Editor and Execution Options

• Read-only Cells:
  Setting edit: false creates a read-only cell. The source code appears on load, and the output is added after the code is executed.

• Immediate Execution:
  Using runbutton: false causes code to execute immediately as it is entered, without requiring a manual click.

• Execution Without Output:
  With include: false, the code is executed but neither the source code nor the output is displayed in the document.

Additional Options for Enhanced Interactivity

• Storing Code:
  Use persist: true to have the editor store user changes locally. The “Start Over” button, controlled by startover, can restore the original code.

• Editor Height:
  Control the visible height of the editor using min-lines and max-lines to suit your layout needs.

• Cross References:
  Use fenced divs with an ID (e.g., ::: {#lst-ref}) for cross-referencing interactive code cells within your document.

Usage Examples

For a concise usage example, see our Interactive Code Blocks Explained page.

Autorun

Automatically execute the code as soon as the WebAssembly engine loads.

Source:

R

```{webr}
#| autorun: true
123 + 456
```

Python

```{pyodide}
#| autorun: true
print(123 + 456)
```

Output:

R

Python

Editable vs. Read-only Cells

Setting edit: false creates a read-only cell. The source code is initially shown and the output is appended once evaluation is complete.

Source:

R (Read-only)

```{webr}
#| edit: false
df <- data.frame(foo = c(1, 2, 3), bar = c(10, 20, 30))
df$foo
df$bar
```

Python (Read-only)

```{pyodide}
#| edit: false
import pandas as pd
df = pd.DataFrame({"foo": [1, 2, 3], "bar": [10, 20, 30]})
print(df["foo"])
print(df["bar"])
```

Output:

R (Read-only)

Python (Read-only)

Note

In read-only mode, only the source code is shown at first; the output appears after the WebAssembly engine finishes evaluating the cell.

Immediate Execution

With runbutton: false, code is evaluated immediately as it is entered—without needing to click a button.

Source:

R

```{webr}
#| caption: Immediate Execution
#| autorun: true
#| runbutton: false
foo <- 123
bar <- 246
foo + bar
```

Python

```{pyodide}
#| caption: Immediate Execution
#| autorun: true
#| runbutton: false
foo = 123
bar = 246
print(foo + bar)
```

Output:

R

Python

Warning

Immediate execution runs code as you type, even if incomplete. Error messages may appear briefly during typing—use with caution.

Autocomplete

Control autocomplete in the code editor. Set completion: false to disable it.

Source:

R

```{webr}
#| autorun: true
#| completion: true
n_mean <- 120
n_sd <- 5

# Type "n_" in the editor to trigger autocomplete suggestions.
```

Python

```{pyodide}
#| autorun: true
#| completion: true
n_mean = 120
n_sd = 5

# Type "n_" in your editor to see context-aware suggestions.
```

Output:

R

Python

Execute Without Output

Set include: false to run code without showing its source or output in the final document.

Source:

R

```{webr}
#| include: false
123
456
include_false_n <- 789
```

```{webr}
print(include_false_n)
```

Python

```{pyodide}
#| include: false
print(123)
print(456)
include_false_n = 789
```

```{pyodide}
print(include_false_n)
```

Output:

R

Python

Storing and Recalling Code

Use persist: true to save user changes locally and startover: false to disable the “Start Over” button.

Note

The “Start Over” button (if enabled) resets the cell to its original content, overriding any persisted changes.

Start Over Disabled

Source:

R (Start Over Disabled)

```{webr}
#| startover: false
foo <- c(2, 4, 6, 8)
foo + 1
```

Python (Start Over Disabled)

```{pyodide}
#| startover: false
foo = [2, 4, 6, 8]
print([x + 1 for x in foo])
```

Output:

R (Start Over Disabled)

Python (Start Over Disabled)

Persist Code

Source:

R (Persist Code)

```{webr}
#| persist: true
foo <- c(1, 3, 5, 7)
foo + 1
```

Python (Persist Code)

```{pyodide}
#| persist: true
foo = [1, 3, 5, 7]
print([x + 1 for x in foo])
```

Output:

R (Persist Code)

Python (Persist Code)

Execution Time Limit

Set a time limit with timelimit: 3 (in seconds). Use timelimit: 0 to disable. The code block stops executing after the specified time, providing a safety net for infinite loops or problematic user code.

Source:

R

```{webr}
#| timelimit: 3
while (TRUE) {
  # Infinite loop for testing; stops after 3 seconds.
}
```

Python

```{pyodide}
#| timelimit: 3
while True:
    pass  # Infinite loop for testing; stops after 3 seconds.
```

Output:

R

Python

Editor Height

Control the editor’s visible height with min-lines and max-lines.

Source:

R

```{webr}
#| min-lines: 6
#| max-lines: 10
x <- 173

y <- 205

x + y
```

Python

```{pyodide}
#| min-lines: 6
#| max-lines: 10
x = 173

y = 205

print(x + y)
```

Output:

R

Python

Cross References

For cross-referencing interactive code cells, use fenced div syntax with an ID.

Example Source

::: {#lst-ref}
```{webr}
mod <- lm(mpg ~ cyl, data = mtcars)
summary(mod)
```
An interactive R code block demonstrating a linear model.
:::

See @lst-ref for details.

Example Output

Listing 1: An interactive R code block demonstrating a linear model.

See Listing 1 for details.