Embedding Retool and Public Apps

🚧

This probably won't work on non-HTTPS websites!

Our authentication scheme requires Secure Cookies which only work in an HTTPS environment. Most modern browsers will not allow the inner iFrame to access these cookies, and the embedded Retool will auto-logout.

You can embed Retool via our SDK, share your app publicly through an iFrame, or use our pre-built React wrapper.

Embedding Retool

Quick start: vanilla JavaScript

Include the Retool SDK and then initialize the dashboard using the following Javascript call.

<script src="https://cdn.tryretool.com/embed.js"> </script>
...
<div id="container" style="height:100vh; width:100vw"/>
<script>
var rt = window.retool.RetoolDashboard(document.getElementById('container'), 'http://yourco.retool.com/editor/test_embeds')
</script>

Quick start: React

Install the react-retool npm module and import into your project.

// with npm
$ npm install react-retool  --save

// with yarn
$ yarn add react-retool
import Retool from 'react-retool';

function App() {
  return (
    <Retool url="https://retoolin.tryretool.com/embedded/public/f7607e1f-670a-4ebf-9a09-be54cf17181e"/>
  );
}

export default App;

Visit the README on npm for detailed documentation about the React wrapper (link).

Example: vanilla JavaScript

Here's a quick and simple example to get a feel for how to embed Retool in other web applications.

First, create a new HTML file and copy paste the below snippet in. Make sure to replace the placeholder URL with your actual Retool domain.

<html>
  <head>
    <script src="https://cdn.tryretool.com/embed.js"> </script>
    <script>
function incrementCompanyId () {
  var d = document.getElementById('companyid');
  var curValue = parseInt(d.textContent)
  d.textContent = String(curValue + 1)
}
    </script>
  </head>
  <body>
    <h1> Company id</h1><p id="companyid">13</p> <button onclick="incrementCompanyId()"> increment me </button>
    <h1> User id</h1><p>1433</p>
    <div style="height: 800px; width: 100%;" id='container'></div>

    <script>
var rt = window.retool.RetoolDashboard(document.getElementById('container'), 'https://retool.yoursite.com/apps/embedded-app')
    </script>
  </body>
</html>

Next, try pulling in some information from the host page like this:

We used the "Parent Window Query" and supplied the CSS selector for the company id in our host page (#companyid). Then we created a text component, and rendered that value using {{ query1.data }}.

If you press on the "Increment me" button - you'll see that Retool automatically picks up the changes from the host page.

Example: React

Here's a similar example to the one above, but using React.

import React from 'react';
import Retool from 'react-retool'

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = {value: 0};
  }

  buttonClicked(event) {
    this.setState({value: this.state.value+1});
  }

  render() {
    return (
      <div className="App">
        <div className="parent-react-app-container">
          <h1>I am a react app</h1>
          <h2>Value Retool will read on load: <span id="id-value-retool-reads">hello</span></h2>
          <div>
            <h2><span id="other-id-value-retool-reads">{this.state.value}</span></h2>
            <button onClick={this.buttonClicked}>Increment Dynamic Value</button>
          </div>
        </div>
        
        <div className="retool-box">
          <Retool url="https://retool.yoursite.com/apps/embedded-app"/>
        </div>
      </div>
    );
  }
}

export default App;

This example also relies on a Retool app with Parent Window Queries reading the values from the parent page.

Parent Window Query reading the value of the element with id="id-value-retool-reads"Parent Window Query reading the value of the element with id="id-value-retool-reads"

Parent Window Query reading the value of the element with id="id-value-retool-reads"

Sending Messages to the Parent Application

Embedded Retool applications can use Parent Window Queries to read values in from the parent application. What if you wanted to send a message in the other direction, from the embedded application to the parent application? You can use a Retool JavaScript query to accomplish this via the browser's postMessage API.

For example, if we wanted to send the current_user's email address to the parent application, it might look like this:

parent.postMessage(current_user.email, 'https://retool.yoursite.com/apps/embedded-app')
Posting a message to the parent application.Posting a message to the parent application.

Posting a message to the parent application.

There are different ways the parent application can listen to and handle events. The specific implementation will vary, but for illustrative purposes here is a simple example of code that the parent application could include:

window.addEventListener('message', function(e) {
    console.log('Parent window received: ', e.data);
}, false);

📘

Tip: Hiding the Retool nav bar

You can hide the Retool navigation bar using the _hideNav=true query parameter. Similarly, you can hide the query timer using _hideTimer=true.

User Authentication in Embedded Apps

It is often the case that you have an existing admin tool that you're embedding Retool apps inside of. This is a nice way to keep the process of switching to Retool simple for end-users, as they can continue to access the tool they're familiar with while allowing developers to build net-new functionality in Retool. Managing authentication between the parent application and the embedded Retool applications can be challenging. This section describes some common patterns to address these challenges.

Can I pass the authentication state from my parent application into Retool?
This is a common question. In short, no. However, in many circumstances, things can be set up to provide very similar behavior as if we were able to directly pass authentication state between the two applications.

User Authentication in Embedded Public Apps

Public Retool apps don't require authentication. If you're embedding a public Retool app into your existing web application, you don't need to do anything to handle the user's state, because there is no user signed into Retool.

User Authentication with SAML/OIDC SSO

Setting up SAML or OIDC SSO is the best way to handle authentication of embedded Retool apps. As long as your existing web application uses the same SSO Identity Provider (IDP) as Retool, the user's authentication state can easily be shared between the two.

Avoiding Double-login

If you configure your web application and Retool to use the same SSO IDP, a user might SSO into the web application, then have to SSO into the embedded Retool application. Although this will work, it is an undesirable and confusing flow for the user. Rather than prompting a login screen, you can set up Retool to automatically try to sign the user in with SSO. This will work if the user has an existing, authenticated session on the IDP — we know they will because they're signed into that parent application.

To configure this, set the TRIGGER_SAML_LOGIN_AUTOMATICALLY, or TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY (depending on if you're using SAML or OIDC SSO) environment variable to true in your docker.env file.

Public Apps

You can share your Retool app publicly via a public link, and embed it in an iFrame in other applications or web pages. To get started, head over to the app you want to share, and make sure you're in edit mode. Click the "Share" button on the top right of your screen, and select the "Public" tab. You should see a link that you can quickly copy and share.

📘

Public apps and Retool plans

Public apps are only available on the Business and Enterprise plans.

Here's an example of an embedded public Retool app from our Working with select components tutorial, via an iFrame:

You can add optional password protection to your public apps, too.

The authentication scheme here isn't rock solid though, so don't put sensitive data behind a password protected public Retool app.

On-premise Setup

If you're looking to embed a Retool app that's hosted via an on-premise Retool instance, please double check your environment variables. The COOKIE_INSECURE environment variable must be set to false.


Did this page help you?