November 16, 2016 - VitoMd and the Evil Machine

Hello Riot.js:quick tutorial about this awesome lib


Riot.js ( is a powerful minimalistic UI/DOM javascript library with clean and concise syntax . It has a tiny size(10.17kb). You can write the code in plain Javascript, CoffeeScript, Typescript or ES6. Its goal is to build reusable components (called tags).

In this tutorial I´m going to show some basic features and code examples, so you can see how easy is to build a javascript application using Riot.js. We are going to use Riot.js 3.2 .


First look

I´m going to use Plunker to quickly show you the features, but if you want to do it locally in your machine, I recommend you download the latest version of Node.js and clone (or download) a Riot starter kit, so you can quickly begin playing with Riot.js. For example, I created this project riot_starter_kit that includes a test framework and a server to run the project.

Writing our first tag

In Riot.js a tag is a component that contains HTML, javascript and CSS in the same file. You can use variables in HTML, call functions and manage events. We are going to create an example.tag to show some Riot.js features.

Go to, double click on script.js to change the filename to example.tag and add this content:

  <h1>{ message }</h1>
    this.message = 'Hello Riot'

This tag contains html and also the script tag that wrap our javascript code. You can see that we can display variables in html easily with { }

Then we need to load the Riot.js library and also load our tag. Edit the index page to look like this:


  <script type="text/javascript" src=""></script>
  <script type="riot/tag" src="./example.tag"></script>

  <script type="text/javascript">

We are loading the tag in the html using just <example></example>, then we load the Riot.js library and also our tag (check that the type is riot/tag). Then we call riot.mount('*') to load all our tags.

Run the Plunker and you should see the Hello Riot message (if you have any problem check the link to the full code at the end of this tutorial) Now we have a working Riot.js project with an example tag.

As you can see we are not using semicolons in the code. This is part of the minimalistic style that Riot.js follows.

Passing parameters to the tag

We can pass parameters to the tag and then read them using the opts property in our tag. So let´s change the tag code to :

  <h1>{ message }</h1>
    this.message = opts.message

In the index page pass the message parameter to the tag, like this. <example message="Hello Riot.js (from parameters)"></example> It should print the message correctly.

Also Riot has the option to pass parameters when you mount the tag, for example: riot.mount('example', {message:'Hello'})

Event handling

Now we want to add an onclick event in our message that will change the text to upper case when clicked. We are going to add the onclick event in the h1 tag and then add an uppercase method inside the script section, like this:

  <h1 onclick={uppercase}>{ message }</h1>
    this.message = opts.message
    uppercase() {
      this.message = this.message.toUpperCase()

You can see that our method is defined with a similar syntax as es6 ,but is not es6 is a syntactic sugar provided by Riot.js. Also you can write the methods like this:

this.uppercase = function() {
  this.message = this.message.toUpperCase()

Accessing the DOM

Riot.js 3 can access html elements using the ref attribute (old versions of riot used the id or name as reference). To show this we will add an input that will change the message in a keyup event. We add the ref attribute with a unique name and then we get the value using this.refs.input_text

<input onkeyup={show_text} ref="input_text"/>
this.show_text = function(e) {
  this.message = this.refs.input_text.value

This works like this: each time we press a key, it will fire the event and call our method (show_text). Then it will access the html input using the reference and get the value with this.refs.input_text.value and assign it to the message. It will automatically update the tag.


Conditionals let you show / hide elements based on a condition. Riot.js provides tree options:

  • if: add (true value) or remove (false value) the element from the document.
  • show: show the element using style=”display: ‘’” when the value is true.
  • hide: hide the element using style=”display: none” when the value is true.

We will add a new button that when clicked will hide/show our message:

  <button onclick={toggle_message}> toggle message </button>

Add a new boolean variable to know if we should show or hide our message:

this.show_message = true

Add the show conditional based on the previous boolean:

  <h1 show={this.show_message} onclick={uppercase}>{ message }</h1>

Finally, create a new method that will show/hide the message. This will be called from our button:

  this.toggle_message = function(e) {
    this.show_message = !this.show_message

That´s it! if you want to check the full code go here:

Share this post on Twitter