Hackernoon logoNPM ReactJS package for Microsoft Immersive Reader by@sinyaa

NPM ReactJS package for Microsoft Immersive Reader

Aleksey Hacker Noon profile picture


Aleksey is Sr. Engineering Manager with over 15 years of experience in delivering SW solutions.

Immersive Reader is an Azure Cognitive Service for developers who want to embed inclusive capabilities into their apps for enhancing text reading and comprehension for users regardless of age or ability.  Students can color code and label words to indicate their part of speech, user read the text aloud feature, translate words and more.

The technology was proven to improve learning of ESL students. According to Microsoft:

“The analysis indicated that the students who used Learning Tools (Immersive Reader) had significantly more growth in reading comprehension compared to the historical cohort, after controlling for variables known to be related to reading comprehension”.

Through proprietary artificial intelligence software, JAAS Foundation created an online portal that delivers a variety of educational games, learning videos and reading materials to underprivileged students primarily directed at teaching English. Schools and teachers can tailor the portal to meet the unique needs of their students or even create their own games.

Integrating Immercieve Reading capabilities into DTML.org seemed like a natural fit. DTML.org is ReactJS website which is connected to MVC.NET APIs hosted on Azure with Azure SQL backend. While immersive Reader has comprehensive documentation, the tutorials on Microsoft site does not cover using Immersive reader in ReactJS websites.

The first step is to install https://github.com/microsoft/immersive-reader-sdk with npm:

npm install @microsoft/immersive-reader-sdk

or yarn

yarn add @microsoft/immersive-reader-sdk

In order to make Immersive Reader re-usable across your ReactJS application it is beneficial to wrap it into a Component which can be referenced across your app. ReactJS Components let you split the UI into independent, reusable pieces, and think about each piece in isolation.

Your component should import launchAsync and renderButtons functions from immersive reader SDK:

import { renderButtons, launchAsync }  from  "@microsoft/immersive-reader-sdk";

To make that control fully abstracted with need to have a capability to pass text title, text body, user locale and Azure token URL into Immersive Reader Componet.

class ImmersiveReader extends Component {

constructor(props) {
	this.state = {
        title: props.title,
        text: props.text,
        locale: props.locale,
        tokenURL: props.tokenURL

Note: Immersive Reader needs a token to authorize calls to Azure Congnitive Services Immersive Reader endpoint. The token endpoint should be setup as a backend service based on this instructions. This is standard way of getting Azure Client token.

The next step is to render Immersive Reader button. It is can be done by retruning a button in our Component render function and invoking renderButtons () function from the SDK to apply correct styles on that button.

  componentDidMount () {

render() {
 return (

OnClick LaunchReader function would fetch a token from provider URL and invoke Imersive Reader.

LaunchReader(tokenURL) {
      .then(response => {
	 if (response.ok) {
          var body =response.json();
          const options = { "uiZIndex": 2000 };
          const subdomain = body.subdomain;
          const data = {
              title: this.props.title,
              chunks: [{
                  content: this.props.text,
                  mimeType: "text/html"

      launchAsync(response, subdomain, data, options)
      .catch(function (error) {
      console.log("Error in launching the Immersive Reader");

Now you can place immersive reader Component across your ReactJS application with simple code similar to below:

     locale ={this.state.userLanguage} 
     tokeURL= {this.state.tokenURL} /> 

The code would render a button which invokes Immersive Reader. Here is how it looks on DTML Platform


You can view full version of Immersive Reader JS Control in Github repository here or use it directly by installing immersive-reader from npm.

Aleksey Hacker Noon profile picture
by Aleksey @sinyaa. Aleksey is Sr. Engineering Manager with over 15 years of experience in delivering SW solutions.Read my stories


Join Hacker Noon

Create your free account to unlock your custom reading experience.