The main use of this package is to render a vegawidget, which is also an htmlwidget. This function builds a vegawidget using a vegaspec.

  embed = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL,
  base_url = NULL,



An object to be coerced to vegaspec, a Vega/Vega-Lite specification


list to specify vega-embed options, see Details on how this is set if NULL.


integer, if specified, the total rendered width (in pixels) of the chart - valid only for single-view charts and layered charts; the default is to use the width in the chart specification


integer, if specified, the total rendered height (in pixels) of the chart - valid only for single-view charts and layered charts; the default is to use the height in the chart specification


character, explicit element ID for the vegawidget, useful if you have other JavaScript that needs to explicitly discover and interact with a specific vegawidget


character, the base URL to prepend to data-URL elements in the vegaspec. This could be the path to a local directory that contains a local file referenced in the spec. It could be the base for a remote URL. Please note that by specifying the base_url here, you will override any loader that you specify using vega_embed(). Please note that this does not work with knitr. See examples.


other arguments passed to htmlwidgets::createWidget()


S3 object of class vegawidget and htmlwidget


If embed is NULL, vegawidget() uses:

  • getOption("vega.embed"), if that is NULL:

  • an empty call to vega_embed()

The most-important arguments to vega_embed() are:

  • renderer, to specify "canvas" (default) or "svg"

  • actions, to specify action-links for export, source, compiled, and editor

If either width or height is specified, the autosize() function is used to override the width and height of the spec. There are some important provisions:

  • Specifying width and height is effective only for single-view charts and layered charts. It will not work for concatenated, faceted, or repeated charts.

  • In the spec, the default interpretation of width and height is to describe the dimensions of the plotting rectangle, not including the space used by the axes, labels, etc. Here, width and height describe the dimensions of the entire rendered chart, including axes, labels, etc.

Please note that if you are using a remote URL to refer to a dataset in your vegaspec, it may not render properly in the RStudio IDE, due to a security policy set by RStudio. If you open the chart in a browser, it should render properly.


  vegawidget(spec_mtcars, width = 350, height = 350)
# vegaspec with a data URL spec_precip <- list( `$schema` = vega_schema(), data = list(url = "seattle-weather.csv"), mark = "tick", encoding = list( x = list(field = "precipitation", type = "quantitative") ) ) %>% as_vegaspec() # define local path to file path_local <- system.file("example-data", package = "vegawidget") # render using local path (does not work with knitr) vegawidget(spec_precip, base_url = path_local)
if (FALSE) { # requires network-access # define remote path to file url_remote <- "" # render using remote path # note: does not render in RStudio IDE; open using browser vegawidget(spec_precip, base_url = url_remote) }