Events & Theming

Flows support events and theming

Flow events

Your application can listen to events that are happening inside the rendered content.

You can subscribe to these events using an event listener.

benbase-embed.height-updated Triggered whenever the height of the Flow is updated. A new height is sent back in pixels.

Flow Event Example

To prevent Flow iFrames to vertically scroll, you can automatically re-size them whenever benbase-embed.height-updated changes

Note: here iframe is the Flow iframe

window.addEventListener('message', (event) => {
    const { event: eventName, data } = event.data;

    switch (eventName) {
        case 'benbase-embed.height-updated':
            const { height } = data;
            iframe.style.height = `${height}px`;
            logMessage(`📏 Height updated: ${height}px`);
            break;

        default:
            logMessage(`📨 Received unknown event: ${eventName}`);
            break;
    }
});

Flow theming

Flows can be themed based on the following interface:

export interface ColorConfig {
    [string]: string[] // 10 different shades of the color specified in the key 
}

export interface BenbaseTheme {
    fontFamily?: string
    colors?: ColorConfig
    primaryColor?: string
    fontSizes?: {
        xs: string
        sm: string
        md: string
        lg: string
        xl: string
    }
    lineHeights?: {
        xs: string
        sm: string
        md: string
        lg: string
        xl: string
    }
}

In production, you'll need to consult with us to update the theme.

To make development easier when customizing the theme, there is also the option to pass in the theme as a url encoded query param in the Flow's url.

Flow theming example

const theme = {
    fontFamily: 'Beno'
    colors: {
        "partnerColor": [
            "#f53d3d",  // Base Color
            "#ff6666",  // Lighter Shade 1
            "#ff7f7f",  // Lighter Shade 2
            "#ff9999",  // Lighter Shade 3
            "#ffb3b3",  // Lighter Shade 4
            "#ffcccc",  // Lighter Shade 5
            "#df3636",  // Darker Shade 1
            "#c93030",  // Darker Shade 2
            "#b22929",  // Darker Shade 3
            "#9c2323",  // Darker Shade 4
            "#851c1c"   // Darker Shade 5
        ]
    }
    primaryColor: "partnerColor"
    fontSizes: {
        xs: "1rem",
        sm: "1.2rem",
        md: "1.3rem",
        lg: "1.5rem",
        xl: "1.675rem"
    }
    lineHeights: {
        xs: "1rem",
        sm: "1.2rem",
        md: "1.3rem",
        lg: "1.5rem",
        xl: "1.675rem"
    }
}

// Generate the URL parameter
const theme = encodeURIComponent(JSON.stringify(theme))

You can then append the encoded theme to a Flow's url:

<iframe src="https://embed.benbase.com?otp=123&theme={{theme}}`" />

Dark Mode

By default, the flow automatically reacts to the system's dark mode setting. The only way to circumvent this behavior is by using manual mode.

Manual Mode

Use manual mode when your application has its own custom light / dark mode implementation with saved state. In manual mode:

Flow theme is controlled by your application
Flow does NOT react to system preference changes
Theme preference is saved to localStorage when benbase-embed.theme event is received
Saved preference persists across single page transitions
Your application's theme state is always respected when passing in color_mode_detection=manual and default mode state

To set-up:

Enable manual mode and pass the default theme state (default theme state is required if using dark mode by default):

<!-- If dark mode is your default -->
<iframe src="https://embed.benbase.com/employee?otp={otp_code}&color_mode_detection=manual&dark_mode=true"></iframe>

<!-- If light mode is your default -->
<iframe src="https://embed.benbase.com/employee?otp={otp_code}&color_mode_detection=manual"></iframe>

Sync theme changes using postMessage events (see Sending Flow Events below)

Sending Flow Events

Whenever the theme changes in your application state in order to sync changes to the flow, you can send the following event:

Event Format:

{
  type: "benbase-embed.theme",
  theme: "light" | "dark"
}

Example:

// Get reference to iframe
const iframe = document.getElementById('flow');

// Send theme update
iframe.contentWindow.postMessage({
  type: "benbase-embed.theme",
  theme: "dark"
}, "*");