Interactive Code Blocks
Dynamic evaluation of user provided code and data visualisation
The quarto-live extension provides WebAssembly powered cells that can be used in Quarto HTML documents to provide dynamic evaluation of user provided code and data visualisation.
Interactive editor
Add an interactive editor to your Quarto HTML document using the webr code cell for R code, or the pyodide code cell for Python code. The editor will be pre-populated with the original contents of the code cell. The code can be changed by the user and evaluated by clicking the “Run Code” button.
Source
```{webr}
for (x in 1:5) {
print(10 + x)
}
``````{pyodide}
for x in range(1, 6):
print(10 + x)
```Output
Read-only cells
Setting edit: false will create a read-only cell. Read only cells are displayed similarly to the usual pre-rendered code blocks, but are executed on the client under WebAssembly.
Source
```{webr}
#| edit: false
df <- data.frame(foo = c(1, 2, 3), bar = c(10, 20, 30))
df$foo
df$bar
```Output
Note
In this mode only the source code will be shown when the page initially loads. After the WebAssembly engine has finished loading and evaluating the code, its output will be added to the cell dynamically.
Autorun
Setting autorun: true evaluates initial code cell contents automatically, once the WebAssembly engine has loaded into the page. That is, you do not need to click “Run Code” to see the initial output.
Source
```{webr}
#| autorun: true
123 + 456
```Output
Immediate execution
Setting runbutton: false will remove the “Run Code” button from the editor UI. In this mode code is evaluated immediately as it is entered into the editor.
Source
```{webr}
#| caption: Immediate Execution
#| autorun: true
#| runbutton: false
foo <- 123
bar <- 246
foo + bar
```Output
Warning
With immediate execution code is executed as it is typed, including partially completed statements. This means that you may see error messages flashing by as code is entered or modified in the editor.
This might be distracting and confusing for new learners, and so this mode should be used carefully. A debouncing feature is planned for the future to help mitigate the issue.
Autocomplete
Context aware autocomplete suggestions are shown in the code editor. This can be disabled by setting the cell option completion: false.
Source
```{webr}
#| autorun: true
#| completion: true
n_mean <- 120
n_sd <- 5
# Type "n_" to see context aware suggestions
```Output
Execute without output
Setting the cell option include: false will execute code in the WebAssembly engine without adding its source code or any output to the resulting document. The option is equivalent to setting echo: false, output: false.
Source
```{webr}
#| include: false
123
456
include_false_n <- 789
```
```{webr}
print(include_false_n)
```Output
Storing and recalling code
Initial editor contents are stored and can be recalled at any time by clicking the “Start Over” button. If required, the “Start Over” button can be disabled by setting the startover: false cell option.
Source
```{webr}
#| startover: false
foo <- c(2, 4, 6, 8)
foo + 1
```Output
Code entered by users can be automatically saved to web browser local storage by setting the persist: true option. When enabled, evaluated code is stored and will be recalled into the editor when the HTML document is reloaded.
Source
```{webr}
#| persist: true
foo <- c(1, 3, 5, 7)
foo + 1
```Output
Note
The “Start Over” button will restore the original code block contents, overriding any code that has been persisted in browser storage.
Execution time limit
Setting the timelimit code cell option will set a time limit for code execution, in seconds. This provides a useful escape hatch for problematic user code that is very long running or stuck in an infinite loop.
The default time limit is 30 seconds and setting timelimit: 0 will disable the limit.
Source
```{webr}
#| timelimit: 3
while (TRUE) {
# Loop, infinitely
}
```Output
Editor height
The editor height can be controlled through the min-lines and max-lines code cell options. Internal empty lines included in the source cell contents are retained.
The min-lines option sets the minimum height of the editor. When there are fewer lines of code, empty space is shown in the remaining space.
The max-lines option sets the maximum height of the editor. When there are additional lines of code, the editor container can be scrolled vertically.
Source
```{webr}
#| min-lines: 6
#| max-lines: 10
x <- 173
y <- 205
x + y
```Output
Cross references
Cross-references to interactive code listings should be written using fenced div syntax. Create a fenced div with an id starting with lst-, then include the interactive code cell followed by the caption.
Source
::: {#lst-ref}
```{webr}
mod <- lm(mpg ~ cyl, data = mtcars)
summary(mod)
```
An interactive R code block, with an example of fitting a linear model.
:::
See @lst-ref for details.Output
See Listing 1 for details.