README.md
In vegawidget: 'Htmlwidget' for 'Vega' and 'Vega-Lite'

vegawidget

Vega-Lite is an implementation of the grammar-of-graphics, rendered in the browser with interactivity.

The goal of vegawidget is to render Vega-Lite and Vega specifications as htmlwidgets, and to help you communicate with a Vega chart using JavaScript or Shiny. Its ambition is to be a low-level interface to the Vega(-Lite) API, so that other packages can build upon it.

Accordingly, this package may be useful to:

build (using lists of lists) re-usable Vega and Vega-Lite specifications for deployment elsewhere.
develop higher-level, user-friendly packages to compose specific types of plots, or even to build a general ggplot2-like framework, using this package as the rendering foundation.

vegawidget now supports the last two Vega-Lite major-versions, currently versions 5 and 4.

However, for a given R session (e.g. rendering of an RMarkdown file), the vegawidget() function can use only one major-version; this version is determined using the $schema element of the first vegaspec evaluated using vegawidget().

This restriction does not apply to the image functions, e.g. vw_to_svg(), or to the compilation function, vw_to_vega().

use vega_version_all() to see the available versions:

library("vegawidget")

vega_version_all()
#>   widget vega_lite   vega vega_embed
#> 1    vl5     5.5.0 5.22.0     6.20.8
#> 2    vl4    4.17.0 5.17.0     6.12.2

Compiling a spec and creating an image now uses the V8 package, rather than depending on a local installation of nodejs.

You can install vegawidget from CRAN with:

install.packages("vegawidget")

The development version of vegawidget is available from GitHub with:

# install.packages("devtools")
devtools::install_github("vegawidget/vegawidget")

Note: There are documentation websites for both the CRAN version and the development version of this package.

Vega(-Lite) specifications are just text, formatted as JSON. However, in R, we can use lists to build specifications:

library("vegawidget")

spec_mtcars <-
  list(
    `$schema` = vega_schema(), # specifies Vega-Lite
    description = "An mtcars example.",
    data = list(values = mtcars),
    mark = "point",
    encoding = list(
      x = list(field = "wt", type = "quantitative"),
      y = list(field = "mpg", type = "quantitative"),
      color = list(field = "cyl", type = "nominal")
    )
  ) %>% 
  as_vegaspec()

The as_vegaspec() function is used to turn the list into a vegaspec; many of this package’s functions are built to support, and render, vegaspecs:

spec_mtcars

The rendering of the chart above depends on where you are reading it:

On this package’s pkgdown site, it is rendered as part of an HTML environment, showing its full capabilities.
At its GitHub code site, the chart is further rendered to a static SVG file, then incorporated into the Markdown rendering.

A learnr tutorial is available: learnr::run_tutorial("overview", package = "vegawidget").

For more, please see our Getting Started article. Additionally, the Vega-Lite website has a comprehensive introduction.

Other articles for this package:

Specify using vegaspec: how to construct and render a vegaspec.
Render using vegawidget: advanced rendering options.
Extend using Shiny: how to interact with Vega charts using Shiny.
Extend using JavaScript: how to interact with Vega charts using JavaScript.
Create Images: how to create and save PNG or SVG images.
Work with Dates and Times: dates and times in Vega(-Lite) work a little differently from R.
Import into Other Packages: how to import vegawidget functions into your package, then re-export them.

Alicia Schep has been instrumental in guiding the evolution of the API, and for introducing new features, particularly the JavaScript and Shiny functions.
Haley Jeppson and Stuart Lee have provided valuable feedback and contributions throughout the package’s development.
Bob Rudis and the vegalite package provided a lot of the inspiration for this work, providing a high-level interface to Vega-Lite.
The Altair developers, for further popularizing the notion of using a programming language (Python) to create and render Vega-Lite specifications.
The Vega-Lite developers, for providing a foundation upon which the rest of this is built.

Contributions are welcome, please see this guide. Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.