Appearance

Get Started ​

Mosaic can be imported for use in JavaScript projects, leveraged within Jupyter notebooks, or deployed alongside a standalone DuckDB server.

Use in JavaScript ​

Include the desired Mosaic libraries in your project dependencies and import them as part of your application. For a working standalone example, take a look at the Cross-Filter Flights 10M notebook on Observable.

The snippet below imports vgplot, configures the coordinator to use DuckDB-WASM, and creates a plot with a single areaY mark to produce a time-series chart for the database table "stocks". To access the central coordinator, use the coordinator() method, which is exported by Mosaic core and also re-exported by Mosaic vgplot.

js
import * as vg from "@uwdata/vgplot";

// configure the coordinator to use DuckDB-WASM
// creates a new database instance running in-browser
vg.coordinator().databaseConnector(vg.wasmConnector());

// load data into the database
// executes a query generated by the loadCSV helper
vg.coordinator().exec(vg.loadCSV("stocks", "stock-data.csv"));

// create an area chart, returned as an HTML element
// you can subsequently add this to your webpage
const chart = vg.plot(
  vg.areaY(vg.from("stocks"), { x: "Date", y: "Price" })
);

Use in Python + Jupyter ​

Mosaic ships a Python API for building interactive visualizations in Jupyter and marimo notebooks. See Mosaic vgplot in Python and the Jupyter widget docs to get started.

Deploy in Observable Framework ​

Mosaic-powered visualizations can be in deployed dashboards or data apps published with Observable Framework. For guidance on deploying Mosaic and using DuckDB to prepare data, see the Mosaic + Framework example site.

Use with LLMs ​

The documentation is also available in an LLM-friendly plain-text format following the llms.txt convention. Point an AI assistant at these files, or paste their contents into a chat, to give it context about Mosaic:

  • llms.txt — an index of the documentation with links to each page.
  • llms-full.txt — the full documentation concatenated into a single file.

Run and develop locally ​

To run Mosaic examples on a local DuckDB server or work on Mosaic development, make a local clone of the Mosaic GitHub repository.

Installation ​

For local installation you should have pnpm and node version 18 or higher.

Run Examples ​

After installation, you can run examples locally, using either DuckDB-WASM or a DuckDB server to load and process data.

  • Run pnpm dev to launch a local web server and view examples. By default, the examples use DuckDB-WASM in the browser. The socket and rest connectors will only work if a local DuckDB server is running. For greater performance, launch and connect to a local DuckDB server as described below below.

To launch a local DuckDB server:

  • Install hatch, if not already present.
  • Run pnpm server to launch the duckdb-server. This runs the server in development mode, so the server will restart if you change its code.