Your Svelte components can seamlessly react to your Observable JavaScript code, making it quick and easy to build bespoke visuals that animate in response to user inputs or other changing data in your document.
đź“‹ Prerequisites
You’ll need to install two things to run Sverto:
⚙️ Installation
Install the project extension using:
quarto use template jimjam-slam/sverto
Then run:
npm install
This will add the extension itself (which includes some project scripts) to the _extension
folder, as well as a few other files.
📦 What’s in the box?
When you use the Sverto template in a project, it creates some files for you:
example.qmd
: an example Quarto doc that uses a Svelte component. If you’re adding Sverto to an existing document, you can delete this.Circles.svelte
: an example Svelte visualisation. If you have a Svelte component that you want to use instead, you can delete this.package.json
: this is used to keep track of the dependencies of your Svelte components. You should add this to version control.package-lock.json
is created once you runnpm install
. You should add this to version control.node_modules/
: This folder is created once you rumnpm install
. Don’t add it to version control.
🎉 Use
Here’s the quick guide to add a Svelte component you’ve written to a Quarto doc:
Step 1: add Svelte to your document
In the document frontmatter, add sverto
to filters
, and add one or more .svelte
files to sverto.use
:
---
title: "My document"
filters: ["sverto"]
sverto:
use:
- example.svelte
---
Step 2: bring your Svelte component to life
Use an Observable JS chunk to instantiate your Svelte component.
```{ojs}
myChart = new example.default({
target: document.querySelector("#chart")
})
```
:::{#chart}
:::
- the
target
is where it will appear. This needs to be an existing part of the document — you can put a Pandoc div right after this code, or put one anywhere else on the page example
is the file name of your Svelte component, without the file extension (so if your file is calledexample.svelte
callexample.default()
)- if your Svelte component has any
props
that don’t have defaults built in, supply default values here for them too. Don’t put reactive OJS code in here; we’ll update the props separately!
Step 3: make your visual reactive
If your visual has props
that allow it to change or transition in response to other OJS code, you can update it by assigning the prop directly.
For example, if we have a dataset called myData
in OJS, and a year slider called selectedYear
, we can change a prop called chartData
whenever the user selects a new year like:
.chartData = myData.filter(d => d.year == selectedYear) myChart
If you’re writing a single document, you’re done! Run quarto render
and see your hard work.
To see this all in practice, check out the simple bar chart example.
Step 4 (for websites): set the project type
If you’re using a Quarto website, change the project.type
in _quarto.yml
from website
to sverto
.
This way, your website pages can share Sverto components when you’re rendering the whole website.
The quarto preview
command won’t “live reload” when you modify your Svelte component—but if you modify and save the Quarto doc that imports it, that will trigger a re-render. You may need to hard reload the page in your browser to see the updated Svelte component.
If you want to quickly iterate on a Svelte component you’re building, you might find the Svelte Preview extension for VSCode handy.
Advanced use
🛍 Use other libraries in your Svelte component
If you want to refer to other JavaScript libraries in your Svelte component (like d3, for example), add them to the project using npm install package1 [package2 ...]
. For example:
npm install d3
đź’ Why Sverto?
Quarto helps data scientists and analysts build beautiful documents regardless of their language of choice, and it encourages data analysts and scientists to explore web visualisation by making JavaScript accessible and easy to use.
Quarto makes interactive charts intuitive to write, but animated ones are still a challenge that require either dipping into a high-level JavaScript library or learning a lower-level one like d3.
Svelte is a framework for building charts, web visualisations and even apps in HTML, CSS and JavaScript. Svelte goes out of its way to make writing self-contained components, like charts, comfortable and intuitive.
Svelte has a great playground environment for developing and testing components, but like many web frameworks, the experience is much more complex when you start developing locally.
Sverto aims to make it as easy to build and use animated Svelte charts in Quarto documents as it is to work on them in the Svelte playground: just write a .svelte
file, add it to a Quarto document, and Sverto takes care of the rest.
âť“ Issues
If you have any problems with Sverto, please feel free to create an issue!
Special thanks to Carlos Scheidegger from Posit for his time and advice!