Get started 🚀

Installation

Using hosted file

Thanks to CDN services like SkyPack you can use iframe library directly on your application.

caution

For the iframe to work you might need to acquire an API Key

Vanilla JS

ts
import { setup } from 'https://cdn.skypack.dev/@unionavatars/iframe@v0.3.1'
const iframe = document.querySelector('iframe#your-id')
const client = setup(iframe, { apiKey: '<your-api-key>' })

ts
import { setup } from 'https://cdn.skypack.dev/@unionavatars/iframe@v0.3.1'
const iframe = document.querySelector('iframe#your-id')
const client = setup(iframe, { apiKey: '<your-api-key>' })

caution

The client won't be properly set if the iframe is not yet loaded. If you have an Error about it not being loaded call setup on the onload event of the iframe

ts
import { type Eventer, setup } from '@unionavatars/iframe'
 
let client: Eventer
iframe.onload = () => {
  client = setup(iframe, { apiKey: '<your-api-key>'})
    
let client: {
    on<O extends keyof Outputs = keyof Outputs, D extends Outputs = Outputs>(key: O, cb: Listener<D[O]>): void;
    once<O_1 extends keyof Outputs = keyof Outputs, D_1 extends Outputs = Outputs>(key: O_1, cb: Listener<...>): void;
    off<O_2 extends keyof Outputs = keyof Outputs, D_2 extends Outputs = Outputs>(key: O_2, cb: Listener<...>): void;
    request<K extends keyof Requests = keyof Requests, P extends unknown[] = Parameters<...>, R = ReturnType<...>>(key: K, ...params: P): Promise<...>;
}
}

ts
import { type Eventer, setup } from '@unionavatars/iframe'
 
let client: Eventer
iframe.onload = () => {
  client = setup(iframe, { apiKey: '<your-api-key>'})
    
let client: {
    on<O extends keyof Outputs = keyof Outputs, D extends Outputs = Outputs>(key: O, cb: Listener<D[O]>): void;
    once<O_1 extends keyof Outputs = keyof Outputs, D_1 extends Outputs = Outputs>(key: O_1, cb: Listener<...>): void;
    off<O_2 extends keyof Outputs = keyof Outputs, D_2 extends Outputs = Outputs>(key: O_2, cb: Listener<...>): void;
    request<K extends keyof Requests = keyof Requests, P extends unknown[] = Parameters<...>, R = ReturnType<...>>(key: K, ...params: P): Promise<...>;
}
}

The variable client can be used to do plain requests, or to listen for events. For a more detailed list of what can be done you can refer to the API docs.

With that client you can do things like login, change the logo with set-logo, or list the avatars with avatars.

The calls are done with the request method of the client.

ts
const avatars = await client.request('avatars')
        
const avatars: {
    succeed: boolean;
    data?: Avatar[] | undefined;
    error?: Error | undefined;
}

ts
const avatars = await client.request('avatars')
        
const avatars: {
    succeed: boolean;
    data?: Avatar[] | undefined;
    error?: Error | undefined;
}

React

html
<script type="module">
import { Provider, Iframe, useIframeContext } from 'https://cdn.skypack.dev/@unionavatars/iframe@v0.3.1/react'
function App () {
  const { eventer } = useIframeContext()
  const onClick = () => { eventer.request('goto', 'Register') }
  return <button onClick={onClick}>Go to register</button>
}
const reactRoot = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
)
reactRoot.render(
  <Provider apiKey="<your-api-key>">
    <Iframe src="https://iframe.unionavatars.com" />
    <App />
  </Provider>
)
</script>

html
<script type="module">
import { Provider, Iframe, useIframeContext } from 'https://cdn.skypack.dev/@unionavatars/iframe@v0.3.1/react'
function App () {
  const { eventer } = useIframeContext()
  const onClick = () => { eventer.request('goto', 'Register') }
  return <button onClick={onClick}>Go to register</button>
}
const reactRoot = ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
)
reactRoot.render(
  <Provider apiKey="<your-api-key>">
    <Iframe src="https://iframe.unionavatars.com" />
    <App />
  </Provider>
)
</script>

Vue

html
<script type="module">
import { createApp, defineComponent } from 'vue'
import { Plugin, Iframe, useIframeContext } from 'https://cdn.skypack.dev/@unionavatars/iframe@v0.3.1/vue'
const component = defineComponent({
  template: `
    <Iframe src="https://iframe.unionavatars.com" />
    <button @click="goToRegister">Go to register</button>
  `,
  setup () {
    const ctx = useIframeContext()
    return {
      goToRegister () {
        ctx?.eventer?.request('goto', 'Register')
      }
    }
  }
})
const app = createApp(component)
app.use(Plugin({ apiKey: '<your-api-key>' }))
app.mount('#root')
</script>

html
<script type="module">
import { createApp, defineComponent } from 'vue'
import { Plugin, Iframe, useIframeContext } from 'https://cdn.skypack.dev/@unionavatars/iframe@v0.3.1/vue'
const component = defineComponent({
  template: `
    <Iframe src="https://iframe.unionavatars.com" />
    <button @click="goToRegister">Go to register</button>
  `,
  setup () {
    const ctx = useIframeContext()
    return {
      goToRegister () {
        ctx?.eventer?.request('goto', 'Register')
      }
    }
  }
})
const app = createApp(component)
app.use(Plugin({ apiKey: '<your-api-key>' }))
app.mount('#root')
</script>

Using npm package

caution

For the iframe to work you might need to acquire an API Key

Create a new react project with Vite

shell
yarn create vite example

shell
yarn create vite example

Include the npm package for the @unionavatars/iframe.

shell
yarn add @unionavatars/iframe

shell
yarn add @unionavatars/iframe

Go to the src/main.tsx file and paste this.

Vanilla JS

ts
import { setup } from '@unionavatars/iframe'
 
const iframe = document.querySelector('iframe#id') as HTMLIFrameElement
const client = setup(iframe, { apiKey: '<your-api-key>' })
 
const button = document.querySelector('button#goto-register') as HTMLButtonElement
button.onclick = () => {
  client.request('goto', 'Register')
}

ts
import { setup } from '@unionavatars/iframe'
 
const iframe = document.querySelector('iframe#id') as HTMLIFrameElement
const client = setup(iframe, { apiKey: '<your-api-key>' })
 
const button = document.querySelector('button#goto-register') as HTMLButtonElement
button.onclick = () => {
  client.request('goto', 'Register')
}

React

tsx
import { createRoot } from 'react-dom/client'
import { Provider, Iframe, useIframeContext } from '@unionavatars/iframe/react'
 
function App () {
  const { eventer } = useIframeContext()
  const onClick = () => { eventer?.request('goto', 'Register') }
  return <button onClick={onClick}>Go to register</button>
}
 
const node = document.getElementById('root') as HTMLElement
const root = createRoot(node)
root.render(
  <Provider apiKey="<your-api-key>">
    <Iframe src="https://iframe.unionavatars.com" />
    <App />
  </Provider>
)

tsx
import { createRoot } from 'react-dom/client'
import { Provider, Iframe, useIframeContext } from '@unionavatars/iframe/react'
 
function App () {
  const { eventer } = useIframeContext()
  const onClick = () => { eventer?.request('goto', 'Register') }
  return <button onClick={onClick}>Go to register</button>
}
 
const node = document.getElementById('root') as HTMLElement
const root = createRoot(node)
root.render(
  <Provider apiKey="<your-api-key>">
    <Iframe src="https://iframe.unionavatars.com" />
    <App />
  </Provider>
)

Vue

ts
import { createApp, defineComponent } from 'vue'
import { Plugin, Iframe, useIframeContext } from '@unionavatars/iframe/vue'
 
const component = defineComponent({
  template: `
    <Iframe src="https://iframe.unionavatars.com" />
    <button @click="goToRegister">Go to register</button>
  `,
  setup () {
    const ctx = useIframeContext()
    return {
      goToRegister () {
        ctx?.eventer?.request('goto', 'Register')
      }
    }
  }
})
 
const app = createApp(component)
app.use(Plugin({ apiKey: '<your-api-key>'}))
app.mount('#root')

ts
import { createApp, defineComponent } from 'vue'
import { Plugin, Iframe, useIframeContext } from '@unionavatars/iframe/vue'
 
const component = defineComponent({
  template: `
    <Iframe src="https://iframe.unionavatars.com" />
    <button @click="goToRegister">Go to register</button>
  `,
  setup () {
    const ctx = useIframeContext()
    return {
      goToRegister () {
        ctx?.eventer?.request('goto', 'Register')
      }
    }
  }
})
 
const app = createApp(component)
app.use(Plugin({ apiKey: '<your-api-key>'}))
app.mount('#root')

On the browser you will see something like this:

Press the button to verify it's working

Examples

Some more detailed examples are hosted here: https://github.com/LinkingRealities/iframe-examples

Getting to know more about the API

More information on what can be done with the client inside the Api section.