​
Introduction

When developing a web application with React, you have the option to embed a Latitude data app via a dedicated React component. This method allows for a more interactive embedding experience and provides the capability to manage the app using JavaScript.

There are several benefits to this approach:

  1. Enables your React app to notify the Latitude app when a parameter is modified within your React app.
  2. Allows for the reverse, in which the Latitude app communicates parameter changes back to your React app.
  3. Gives you the ability to execute all or selected queries directly from your React app.
  4. Permits the dispatch of custom events from your React app to the Latitude view.

We have an example application. You can check the source code if you get lost in the process. In Embedding/index.tsx you can see all the options you can pass to the <LatitudeEmbed /> component.

Experiment by modifying the field within YOUR REACT APP and observe the changes in the Latitude app. Next, adjust the same field within the LATITUDE IFRAME and watch how the React app responds. To execute all queries in the example, click the Run button.

And lastly Pick your character and see how Latitude app shows your Star Wars character. May the force be with you!

​
Installation

You need to install our React SDK

npm install @latitude-app/react

In the root of your app you need to initialize the embedding component with defineCustomElements(window) method. This is necessary because under the hood we are using web components and they need to be initialized before using them.

src/index.tsx
```tsx src/app.tsx
import { defineCustomElements } from '@latitude-data/react'
import App from './App'

// This line is necessary
defineCustomElements(window)

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    {/* Your app goes here */}
    <App />
  </React.StrictMode>,
)

And lastly use <LatitudeEmbed /> component to embed the Latitude app.

src/App.tsx
import { LatitudeEmbed } from '@latitude-data/react'

// localhost:3000/some/view is the URL of the view in your Latitude data app
// <LatitudeEmbed /> will embed the view in your React app
export default App () {
  return (
    <LatitudeEmbed url='http://localhost:3000/some/view' />
  )
}

That’s it! 🎉 You have successfully embedded a Latitude data app within your React application.

​
Passing signed params

You can read more about signed params in our documentation. You can pass signed params to the Latitude app.

src/App.tsx
export default App () {
  return (
    <LatitudeEmbed
      url='http://localhost:3000/some/view'
      signedParams='SECRET_SIGNED_PARAMS'
    />
  )
}

​
Passing initial parameters

You can setup the embedding with initial parameters. This is useful when you want to pass some data from your React app to the Latitude app.

src/App.tsx
export default App () {
  return (
    <LatitudeEmbed
      url='http://localhost:3000/some/view'
      params={{ start_year: '2003', end_year: endYear }}
    />
  )
}

​
Request parameter changes

Ask Latitude app to update some specific parameter.

src/App.tsx
import { LatitudeEmbed, changeEmbedParams } from '@latitude-data/react'
export default App () {
  const [endYear, setEndYear] = useState('2005')

  return (
    <>
      <input
        type='text'
        value={endYear}
        onChange={(e) => {
          // Use this method to change the parameters of the Latitude app
          changeEmbedParams({ end_year: value })
          setEndYear(e.target.value)
        }}
      />
      <LatitudeEmbed
        url='http://localhost:3000/some/view'
        params={{ start_year: '2003', end_year: endYear }}
      />
    </>
  )
}

​
Listen to parameter changes

You can listen to parameter changes in the Latitude app and update your React app accordingly.

src/App.tsx
export default function App () {
  const [endYear, setEndYear] = useState('2005')

  return (
    <LatitudeEmbed
      url='http://localhost:3000/some/view'
      params={{ start_year: '2003', end_year: endYear }}
      onParamsChanged={(event) => {
        const params = event.detail.params
        const newEndYear = params.end_year as string
        if (endYear === newEndYear) return

        // Update the end year in your React app
        // when the end year in the Latitude app changes
        setEndYear(newEndYear)
      }}
    />
  )
}

​
Execute queries

You can execute all or selected queries directly from your React app.

src/App.tsx
import { LatitudeEmbed, runEmbedViewQuery } from '@latitude-data/react'

export default function App () {
  return (
    <>
      <button
        onClick={() => {
          // This will run all the queries in your embedded latitude view
          // runEmbedViewQuery({ queryPaths: [] })

          // This will run only `users/total` query
          runEmbedViewQuery({ queryPaths: ['users/total'] })
        }}
      >
        Run
      </button>
      <LatitudeEmbed url='http://localhost:3000/some/view' />
    </>
  )
}

​
Dispatch custom events

You can dispatch custom events from your React app to the Latitude view. This has two parts. First you dispatch the event from your React app and then you listen to it in the Latitude app.

src/App.tsx
import { LatitudeEmbed, triggerCustomEvent } from '@latitude-data/react'

export default function App () {
  return (
    <>
      <button
        onClick={() => {
          // Dispatch a custom event to the Latitude app
          triggerCustomEvent({ message: 'Hello from React!' })
        }}
      >
        Dispatch event
      </button>
      <LatitudeEmbed url='http://localhost:3000/some/view' />
    </>
  )
}

Now in your Latitude view you can listen to this event.

~/your-latitude-project/views/some/view/index.html
<script>
  import { onMount } from 'svelte'
  import { iframe } from '@latitude-data/embedding'

  onMount(async () => {
    iframe.onCustomEvent = async (event) => {
      const data = event.data
      if (!data) return

      console.log(data.value)
      // This will log 'Hello from React!'
    }
  })
</script>

You can do whatever you want with the data you receive in the event. Your imagination is the limit! 🚀

Iframe embeddingReact Components