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

Andi Pavllo
Sep 29, 2015 · 6 min read

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.




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.


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


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:


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


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 this.state.pictures.id.

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.


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 onsen.io on September 29, 2015.

The Web Tub

Pushing the web current through hybrid mobile and PWA…

The Web Tub

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

Andi Pavllo

Written by

The Web Tub

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