Custom Components

Overview

Under the hood an Idyll component is anything that will function as a React component. If you create a custom component in JavaScript, point Idyll to the folder where you created it and it will be available in your markup.

For example, this custom component

// custom.js
const React = require('react');

class Custom extends React.PureComponent {
  render() {
    const { idyll, hasError, updateProps, ...props } = this.props;

    return (
      <div {...props}>
        This is a custom component
      </div>
    );
  }
}

module.exports = Custom;

would be invoked inside of an Idyll file with the following code:

[Custom /]

Notice that the custom component inherits from React.PureComponentrather than React.Component so that rendering is updated only when properties or state change. This speeds up compilation in watch mode.

Updating the Document

Idyll provides a way for your components to push state changes back up to the document. This is how a component is able to affect change through the document. An updateProps method is injected onto the props object that your custom component receives. This function can be called to update variable values and propagate those changes to the rest of the Idyll document.

Example

For example, a component can change the value of a property that it receives, and Idyll will propagate the change to any bound variables on the page.

const React = require('react');
class Incrementer extends React.PureComponent {

  increment() {
    this.props.updateProps({
      value: this.props.value + 1
    })
  }

  render() {
    return (
      <div onClick={this.increment.bind(this)}>
        Click me.
      </div>
    );
  }
}

module.exports = Incrementer;

The Incrementer component could then be used as follows:

[var name:"clickCount" value:0 /]

[Incrementer value:clickCount /]
[Display value:clickCount /]

Notice that even though the Incrementer component doesn't know anything about the variable clickCount, it will still correctly update.

Name resolution

Components lookup is based on filenames. If your component name is MyComponent, it will match files likemycomponent.js or my-component.js. The component filenames are case insensitive.

Custom component are meant for times when more complex and custom code is needed. By default Idyll will look for your custom components inside of a folder called components/. If you wish to change the custom component path, specify it with the --components option, e.g.

idyll index.idl --css styles.css --components custom/component/path/

Manipulating component children

If your component needs to modify the render tree of its children,
https://github.com/idyll-lang/idyll-component-children is a helper library to filter and map the component's children.

Continue to learn how to use references to make your page more dynamic.