Built-In Components

Idyll ships with a handful of components that handle common tasks. They are broken into three categories:

All built-in compononents expose a property onEnteredView that can be used to trigger events when a reader scrolls the page to reveal specific content.



Content inside of an aside component will be displayed in the margin of your document. For example, the consumer complaints article uses the aside component to display a small chart and caption:


  [Chart type:"time" data:complaintsByDate /]
  [caption]Complaints sent to the CFPB each month[/caption]


Content inside of a fixed component will be locked in place, even when the rest of the document scrolls. The scroll example uses the fixed component to keep the dynamic chart in place:


[Chart type:"scatter" data:dynamicData /]


The inline component adds the display: inline-block style property, so that items inside of inline component will be displayed next to eachother. For example, this code,

[inline][img src:"..." /][/inline]
[inline][img src:"..." /][/inline]
[inline][img src:"..." /][/inline]

Will display three images side by side.



The action compoennt allows you to add event handlers to text. For example:

This is regular text, but when you [action onClick:`alert('clicked the text')`]click me[/action], an alert will appear.


  • onClick
  • onMouseEnter
  • onMouseLeave


This will display a checkbox.


  • value - A value for the checkbox. If this value is truthy, the checkbox will be shown


This will display a button. To control what happens when the button is clicked, add an onClick property:


[button onClick`myVar += 1`]Click Me![/button]


This will display a chart. It expects the following properties:

  • data - A JSON object containing the data for this chart. It uses the victory library to handle rendering, so see those docs for more information on what types of data can be passed in.
  • type - The type of the chart to display, can be line, scatter, bar, pie, or time. The time type is a line chart that expects the x values in the data to be in the temporal domain.


[var name:`dataToBeCharted` value:`[
  {x: 0, y: 0.5},
  {x: 3.5, y: 0.5},
  {x: 4, y: 0},
  {x: 4.5, y: 1},
  {x: 5, y: 0.5},
  {x: 8, y: 0.5}
]` /]

[Chart type:"line" data:dataToBeCharted /]


This will render the value of a variable to the screen. It is mostly useful for debugging:


[var name:"myVar" value:10 /]

[Range value:myVar min:0 max:100 /]
[Display value:myVar /]


This will render a dynamic variable to the screen.


[var name:"myVar" value:10 /]

[Dynamic value:myVar /]

The properties are:

  • value: The value to display
  • max: The maximum value.
  • min: The minimum value.
  • interval: The granularity of the changes


This uses KaTeX to typeset mathematical equations. Example:


  y = \int x^2 dx

This component makes it easy to add a title, subtitle, and byline to your article:


  title:"The Title of my Article"
  subtitle:"The subtitle of my article"
  author:"Matthew Conlen"


Embed a github gist


[gist gist:"0f83a12e29b268ffca39f471ecf39e91" file:"particles.idl" /]

This component just acts as syntactic sugar for displaying links inline in your text.

[link text:"the text" url:"https://some.url" /]

is equivalent to [a href:"https://some.url"]the text[/a].


This component displays a range slider. The properties are:

  • value: The value to display; if this is a variable, the variable will automatically be updated when the slider is moved.
  • max: The maximum value.
  • min: The minimum value.
  • step: The granularity of the slider


[var name:"myVar" value:10 /]

[Range value:myVar min:0 max:100 /]
[Display value:myVar /]

Slideshow / Slide

This component is used to dynamically display different content. It can be used to make slideshows, but is generally useful for dynamically displaying different content of any type.


[var name:"slide" value:1 /]

[slideshow currentSlide:slide]
  [slide]This is the content for slide 1[/slide]
  [slide]This is the content for slide 2[/slide]
  [slide]This is the content for slide 3[/slide]

[Button onClick:`slide = 1`]Slide 1[/Button]
[Button onClick:`slide = 2`]Slide 2[/Button]
[Button onClick:`slide = 3`]Slide 3[/Button]


This component will display an SVG file inline using https://github.com/matthewwithanm/react-inlinesvg. This makes it easy to style the SVG with css, as opposed to displaying the svg inside of an image tag.


[SVG src:"path/to/file.svg" /]


Display tabular data. Uses https://github.com/glittershark/reactable under the hood to render the table.


[Table data:`[{columnName1: value, columnName2: value}, {columnName1: value, {columnName2: value}}]` /]



This component makes it easy to insert a Google Analytics code on your page.

[Analytics google:"UA-XXXXXXXXX" /]


The meta component adds context to the page template when building your app for publication. The following variables are available and will be inserted as <meta> properties into the head of your HTML page if you define them:

  • title - the page title
  • description - a short description of your project
  • url - the canonical URL from this project
  • twitterHandle - the author's twitter handle, it will create a link in the twitter card
  • shareImageUrl - the URL of an image to be shared on social media (twitter cards, etc.). This must be a fully qualified URL, e.g. https://idyll-lang.github.io/images/logo.png.
  • shareImageWidth - the width of the share image in pixels
  • shareImageHeight - the height of the share image in pixels

Continue to read about making custom components.