The Web Tub
Published in

The Web Tub

Tutorial: Create a Instagram Gallery App with Onsen UI + React

As you probably already know, Onsen UI is based on AngularJS. Nevertheless, many of our users asked if it’s possible to use it with other frameworks, especially React. In this tutorial, we will show you how to develop a very simple Instagram app by using Onsen UI and React. We will create a simple gallery using React and Onsen UI!

Although the current stable version of Onsen UI is 1.3.11, we will be using the development version of Onsen UI 2.0. We are getting close to releasing the alpha version and it is already quite stable. Onsen UI 2.0 is framework agnostic. It is no longer dependent on Angular, which means it integrates a lot better with other frameworks.

For more info about the new and features of the upcoming Onsen UI 2.0 please take a look at these links:

For those that never heard about it, React (sometimes styled React.js or ReactJS) is an open-source JavaScript library for building performant user interfaces. It is created and maintained by Facebook with the collaboration of Instagram and a community of individual developers and corporations. React is intended to help developers build large scale applications that use data that changes over time. Its goal is to be simple, declarative and composable.

To achieve this goal, React makes use of a Virtual DOM and a patching mechanism, which allow React to only update relevant portions of the application, rather than having to re-render the entire site on each change. This mechanism makes React one of the more performant JavaScript frameworks.

Disclaimer: The images are randomly retrieved from Instagram API, we don’t take any responsibility for the content.


Before starting the development process, there are a few prerequisites. You can download the full project from this GitHub repository.


In this tutorial we will be using React and Onsen UI. You can download the React libraries from this link. To implement this sample app we have used the dev version from React’s GitHub repository but the stable release should work fine.

We are using the development version of Onsen UI which will soon be released as Onsen UI 2.0. In Onsen UI 2.0 we have removed the AngularJS dependency and are instead using Web Components to implement the UI components.

In order to use the development version you can clone the Onsen UI repository and build from source. The build process is very simple and can he found here. Another way is to download the latest build from our website.


We invite you to take a look at the Onsen UI and React documentation in case some concepts are not clear.

Once all the prerequisites have been satisfied, we can start with the development process.


First of all, we need to include the libraries in the project. So start by creating an index.html file and import the following libraries:

We are only importing ons-core.js instead of the onsenui.js file. The ons-core.js file contains everything we need while the onsenui.js file contains Angular bindings which are not required in this app.

JSXTransformer.js is a library already included in the React package. JSX is a JavaScript syntax extension that looks similar to XML. You can use a simple JSX syntactic transform with React. Even if you are still allowed to use plain JS with React, it’s recommended that you use JSX because it is more concise.

jQuery is just there to make AJAX calls. We could have used pure JavaScript to do this, but jQuery makes the code a bit cleaner.

We also need to import the Onsen UI stylesheets so the app displays correctly:

We also define some custom CSS to make the images and buttons display nicely:


The HTML is very simple because almost all the content will be generated by React.

We are just mentioning it because the div element will be the mounting point, to which all the dynamic content will be appended to.


Let’s now take a look at the heart of our app: the React code. First of all, we need to identify the React components to implement. Instances of a React components are created internally in React when rendering. These instances are reused in subsequent renders, and can be accessed in your component methods as this. The only way to get a handle to a React component instance outside of React is by storing the return value of React.render.

In our case, just one component is enough: a PictureList component.

PictureList Component

This is the code that implements the picture list. It will render a <ons-carousel> which is a swipeable carousel element. The component will fetch a list of images from the Instagram API and render them as a list of <ons-carousel-item> elements so the user can browse through them by swiping. When the list of images changes it will automatically refresh the carousel.

We will also add some buttons to enable refreshing the list of images and going back and forth.

Before entering in the details of the component, we need to explain its lifecycle, which is defined in three states:

  • getInitialState: Invoked once before the component is mounted. The return value will be used as the initial value of this.state.
  • componentDidMount: Invoked once, immediately after the initial rendering occurs. At this point in the lifecycle, the component has a DOM representation. The componentDidMount() method of child components is invoked before the ones of parent components.
  • componentDidUpdate: Invoked immediately after the component’s updates are flushed to the DOM. This method is not called for the initial render.

During getInitialState(), we just define an empty state called pictures and a boolean called loading. A state is just an internal data-set which affects the rendering of components. By defining a state, we are telling to the component which values should be available from the first render cycle until the state values are changed. A state should never be used without first declaring it in this manner.

In componentDidMount, we call the refresh() method which retrieves the data from the Instagram API. To access the API key parameter, we use this.props.apiKey. this.props contains all the properties of the component, which can be sent as parameters or be internally defined.

A JSON request will be made and the result, in case of success, will be put in the pictures variable. To conclude, we need to update the pictures state by executing self.setState({ pictures: pictures });.

At this point the state got updated, which means that it will also be rendered. It’s good to notice that this is not the first time that our state has been rendered, also after the creation a rendering event has occurred. We need to render each image contained into the pictures state as an ons-carousel item component. To do that we will use a map function, which is not a React function but it’s already included in JavaScript. The map() function just creates a new array with the results of calling a provided function on every element in this array.

In React, when children are shuffled around or if new components are added onto the front of the list, the identity and state of each child must be maintained across render passes. That’s why we have to uniquely identify each child by assigning it a key, in this case

Final Rendering

At this point, we are almost at the end of the sample app development. We have already rendered internally all the content but how to also render it inside the DOM structure? By using another rendering function, of course!

This time we are rendering the Carousel component, which contains the PictureList component inside the DOM. The second parameter specifies the mounting point, in this case the element with content id.


In this tutorial you have seen how to create a sample Instagram gallery app by using Onsen UI and React. Now you have a basic layout to customize and enrich as you wish. Show us what you are able to do! The idea for this tutorial comes from Tutorialzine’s article 5 Practical Examples For Learning The React Framework.

As always, we want to remind you that Onsen UI is an open source project and a community effort. There is nothing that makes us happier than getting contributions from the community.

A good place to start is the GitHub issues page. If there’s an issue that you would like to solve, go ahead and fork the repository and make a Pull request. We also appreciate new features. Upon receiving a pull request, we will review it as soon as possible.

Another way to contribute is by helping other users on Gitter or Stack Overflow.

Originally published at on September 29, 2015.



Pushing the web current through hybrid mobile and PWA technology. Presented by the Monaca and Onsen UI team.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store