Document - Mounting - 《Riot.js Manual》

Mounting

Mounting

Once a component is created you can mount it on the page as follows:

<body>
  <!-- place the custom component anywhere inside the body -->
  <my-component></my-component>
  <!-- is attributes are also supported -->
  <div is="my-component"></div>
  <!-- include riot.js -->
  <script src="riot.min.js"></script>
  <!-- mount the component -->
  <script type="module">
    // import the component javascript output generated via @riotjs/compiler
    import MyComponent from './my-component.js'
    // register the riot component
    riot.register('my-component', MyComponent)
    riot.mount('my-component')
  </script>
</body>

Custom components inside the body of the page needs to be closed normally: <my-component></my-component> and self-closing: <my-component/> is not supported.

Some example uses of the mount method:

// mount an element with a specific id
riot.mount('#my-element')
// mount selected elements
riot.mount('todo, forum, comments')

A document can contain multiple instances of the same component.

Accessing DOM elements

Riot gives you access to your component DOM elements via this.$ and this.$$ helper methods.

<my-component>
  <h1>My todo list</h1>
  <ul>
    <li>Learn Riot.js</li>
    <li>Build something cool</li>
  </ul>
  <script>
    export default {
      onMounted() {
        const title = this.$('h1') // single element
        const items = this.$$('li') // multiple elements
      }
    }
  </script>
</my-component>

How to use jQuery, Zepto, querySelector, etc.

If you need to access the DOM inside Riot, you’ll want to take a look at the riot component lifecycle. Notice that the DOM elements aren’t instantiated until the mount event first fires, meaning any attempt to select an element before then will fail.

<my-component>
  <p id="findMe">Do I even Exist?</p>
  <script>
    var test1 = document.getElementById('findMe')
    console.log('test1', test1)  // Fails
    export default {
      onMounted() {
        const test2 = document.getElementById('findMe')
        console.log('test2', test2) // Succeeds, fires once (per mount)
      },
      onUpdated() {
        const test3 = document.getElementById('findMe')
        console.log('test3', test3) // Succeeds, fires on every update
      }
    }
  </script>
</my-component>

Contexted DOM query

Now that we know how to get DOM elements in the onUpdated or onMounted callbacks, we can make this useful by also adding a context to our element queries to the root element (the riot tag we’re creating).

<my-component>
  <p id="findMe">Do I even Exist?</p>
  <p>Is this real life?</p>
  <p>Or just fantasy?</p>
  <script>
    export default {
      onMounted() {
        // Contexted jQuery
        $('p', this.root) // similar to this.$
        // Contexted Query Selector
        this.root.querySelectorAll('p') // similar to this.$$
      }
    }
  </script>
</my-component>

Properties

You can pass initial properties for components in the second argument

<script>
  riot.mount('todo', { title: 'My TODO app', items: [ ... ] })
</script>

The passed data can be anything, ranging from a simple object to a full application API. Or it can be a Redux store. Depends on the designed architecture.

Inside the tag the properties can be referenced with the this.props attribute as follows:

<my-component>
  <!-- Props in HTML -->
  <h3>{ props.title }</h3>
  <script>
    export default {
      onMounted() {
        // Props in javascript
        const title = this.props.title
        // this.props is frozen and it's immutable
        this.props.description = 'my description' // this will not work
      }
    }
  </script>
</my-component>

State

Each riot component can use the this.state object to store or modify its internal state.While the this.props attribute is frozen the this.state object is completely mutable and it could be updated manually or via the this.update() method:

<my-component id="{ state.name }-{ state.surname }">
  <p>{ state.name } - { state.surname }</p>
  <script>
    export default {
      onMounted() {
        // this is good but doesn't update the component DOM
        this.state.name = 'Jack'
        // this call updates the state and the component DOM as well
        this.update({
          surname: 'Black'
        })
      }
    }
  </script>
</my-component>

Riot component lifecycle

A component is created in following sequence:

The component object is created
The javascript logic is executed
All HTML expressions are calculated
The component DOM is mounted on the page and “onMounted” callback is calledAfter the component is mounted the expressions are updated as follows:
When this.update() is called on the current component instance
When this.update() is called on a parent component, or any parent upwards. Updates flow uni-directionally from parent to child.The “onUpdated” callback is called every time component tag is updated.

Since the values are calculated before mounting there are no surprise issues such as failed <img src={ src }> calls.

Lifecycle callbacks

You can setup you component lifecycles as follows:

<my-component>
  <script>
    export default {
      onBeforeMount(props, state) {
        // before the component is mounted
      },
      onMounted(props, state) {
        // right after the component is mounted on the page
      },
      onBeforeUpdate(props, state) {
        // allows recalculation of context data before the update
      },
      onUpdated(props, state) {
        // right after the component template is updated after an update call
      },
      onBeforeUnmount(props, state) {
        // before the component is removed
      },
      onUnmounted(props, state) {
        // when the component is removed from the page
      }
    }
  </script>
</my-component>

Any callback receives always the current this.props and this.state as arguments.