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" */
/>