Embedding Idyll in an existing web page

The following instructions assume you are working in a JavaScript environment that supports importing components from npm. If you prefer to embed Idyll using a script tag, see idyll-embed.

The Idyll runtime is available as a React component, allowing you to embed interactive Idyll content anywhere on the web.

To do this, you must first install the dependencies:

$ npm i --save idyll-document idyll-components

then, add it to your page. If you are already using React, you can include this as a standard component:

import IdyllDocument from 'idyll-document'; import * as components from 'idyll-components'; // An example functional component ({ idyllMarkup }) => { return ( <IdyllDocument markup={ idyllMarkup } components={ components } datasets={ {} } />; ) } 

If not, you'll also need to install react and react-dom:

$ npm i --save react react-dom

and can embed it like this:

import React from 'react'; import ReactDOM from 'react-dom'; import IdyllDocument from 'idyll-document'; import * as components from 'idyll-components'; // You must provide idyllMarkup // and the container element (a DOM node). ReactDOM.render( <IdyllDocument markup={ idyllMarkup } components={ components } datasets={ {} } />, containerElement ) 

To add additional components:

import IdyllDocument from 'idyll-document'; import * as components from 'idyll-components'; import IdyllVegalite from 'idyll-vega-lite'; const availableComponents = { ...components, IdyllVegaLite: IdyllVegaLite } // An example functional component ({ idyllMarkup }) => { return ( <IdyllDocument markup={ idyllMarkup } components={ availableComponents } datasets={ {} } />; ) } 

The IdyllDocument component accepts the following options:

<IdyllDocument ast={ast} /* optional, if you want to pass in a precompiled abstract syntax tree instead of markup */ components={components} /* Map of components that may be referenced in markup */ context={context} /* Add custom context hooks (see https://idyll-lang.org/docs/advanced-configuration) for more info */ datasets={datasets} /* Map of datasets that may be referenced in markup */ layout={layout} /* Which layout to use? e.g. "blog", "centered" */ markup={markup} /* String of Idyll markup. Must provide either this OR ast */ theme={theme} /* Which theme to use? e.g. "github" */ />