# Getting Started

For a comprehensive introduction to Vega-Lite, please visit the its web site. An interactive tutorial to vegawidget is available at shinyapps.io.

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

This package is a low-level interface to Vega-Lite and the Vega ecosystem, which has a lot of powerful capabilities, highlighted in this series of articles:

- 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.

To share your Vega(-Lite) creation on the Blocks website, you can use the vegablock package.

## Integration with other packages

Although there is an article dedicated to this aspect of the package, it warrants further emphasis.

This package provides functions to render Vega(-Lite) specifications; although it provides some helpers, it does not provide higher-level functions to build specifications. Rather, this is left to other packages. Even though you can use its functions directly, you are invited to import and re-export them for use in your package.

Accordingly, this package offers a templating function, `use_vegawidget()`, to help you integrate vegawidget functions into your package. For example, it is used to import and re-export vegawidget functions for the altair package.

## Known limitations

The two biggest known limitations are both associated with vegaspecs that contain datasets specified using remote URLs:

- The RStudio IDE may not let you access remote URLs for security reasons. A chart that accesses remote data may not render in the IDE; it will render in a browser window.

- The image functions use nodejs to create SVG strings. We are not able to configure the proxy in our node scripts, so if your computer uses a proxy to access remote data, our functions will not create the images properly.