QSApp React Integration

Usage

Install this component from NPM:

pnpm add @qsapp/react

Import this component into your React page:

import QSApp from '@qsapp/react';

Then use the component within your React page passing your QSApp ID as a property.

<QSApp id=<YOUR_QSAPP_ID> />

Here is a list of all properties the QSApp React Component currently supports:

Property	Description	type	Required?
id	Your QSApp ID	string	Yes
className	CSS classes for styling	string	No
actions	Function from QSApp action	Record<string, (action: string) => void>	No
hideLoadingAnimation	Hides loading animation	boolean	No
loadingAnimation	Loading Animation	ReactNode	No
deferLoading	Wait data loading	boolean	No
onStart	Functions to run on start	() => void	No
onAPI	Functions to run on API	() => void	No
inputActions	Functions on text input	Record<string, (value: string) => void>	No
mode	Use Canvas or Iframe	'canvas'	'iframe'

Receiving QSApp Actions

The actions property allows you to define an action to listen to and a corresponding function from the parent app to run. Example:

    const [show, setShow] = useState(false);

    return (
        <QSApp 
            id="..." 
            actions={{
                'click': () => setShow(true),
            }}
        />
    )

Sending Events to QSApp

We can send events from our React page to the QSApp which can be used to trigger various states. This requires more set up on the React application side and makes use of useRef. By using the useRef property, we gain access to the component's send function, which allows us to pass an event string to the QSApp.

import { useRef } from 'react';
import QSApp, { QSRef } from '@/components/QSApp';

export default function Demo() {
    const qsRef = useRef<QSRef>(null);

    const sendClick = () => {
        if(qsRef.current) {
            qsRef.current.send('CLICK');
        }
    };

    return (
        <button onClick={sendClick}>Button</button>
        <QSApp 
            ref={qsRef}
            id="..."
        />
    )

}

QSApp Functions

Here's a list of the functions which you can use to send Events and manipulate your QSApp Layouts.

Function	Description	type
send	Send events to QSApp	(event: string) => void
setLayoutText	Update a Text Node	(layout: string, element: string, text: string) => void
getLayoutInput	Get text from Input Node	(layout: string, element: string ) => void
setLayoutImage	Set Sprite node image	(layout: string, element: string, url: string) => void

Updating Layout

You can update a layout similarly to sending an action to the QSApp. One such method to update the Layout would be updating a Layout's Text Node. This uses the function setLayoutText which takes three parameters, the Layout Name, the Element to be updated, and the Text to update it with.

import { useRef } from 'react';
import QSApp, { QSRef } from '@/components/QSApp';

export default function Demo() {
    const qsRef = useRef<QSRef>(null);

    const updateText = () => {
        if(qsRef.current) {
            qsRef.current.setLayoutText('My_Layout', 'My_Element', 'Updated Text');
        }
    };

    return (
        <button onClick={updateText}>Button</button>
        <QSApp 
            ref={qsRef}
            id="..."
        />
    )

}

TypeScript Note

When using useRef with a QSApp, be sure to import and use the QSRef type from the QSApp component. This will allow for easier typing and the ability to properly call the associated QSApp functions.