Overlay Components

Overlay related components: StartupScreen, LoadingOverlay, StatusOverlay.

StartupScreen

Startup guide page component, used for scenarios requiring manual user activation (e.g., iOS iframe).

Basic Usage

import {useState} from 'react';
import {PilotKit, StartupScreen} from '@bdky/aaas-pilot-kit-react-widget';
import '@bdky/aaas-pilot-kit-react-widget/styles.css';

function App() {
    const [showStartup, setShowStartup] = useState(false);

    return (
        <PilotKit
            onNeedManualActivation={() => setShowStartup(true)}
            {...props}
        >
            <StartupScreen
                show={showStartup}
                title="Start Conversation"
                buttonText="Activate"
                avatar={<img src="/avatar.jpg" alt="" />}
                hintText="For better recognition results, please experience in a quiet environment"
                onReady={() => setShowStartup(false)}
            />
        </PilotKit>
    );
}

Props

Property	Type	Default	Description
show	boolean	false	Whether to show
className	string	-	Custom class name
style	CSSProperties	-	Custom style
backgroundUrl	string	-	Background image URL
title	string	'Start Conversation'	Title
buttonText	string	'Start'	Button text
hintText	string	-	Hint text
avatar	ReactNode	-	Avatar element
onReady	() => void	-	Activation success callback

Custom Rendering

<StartupScreen show={showStartup}>
    {({onStart, isActivating}) => (
        <div className="my-startup">
            <h1>Welcome</h1>
            <button onClick={onStart} disabled={isActivating}>
                {isActivating ? 'Activating...' : 'Start Experience'}
            </button>
        </div>
    )}
</StartupScreen>

Style Customization

Class Name	Description
.apk-startup-screen-wrapper	Outer container
.apk-startup-screen	Inner container
.apk-startup-screen__content	Content area
.apk-startup-screen__avatar-wrapper	Avatar wrapper
.apk-startup-screen__avatar-outer	Avatar outer layer
.apk-startup-screen__title	Title
.apk-startup-screen__hint	Hint text
.apk-startup-screen__button	Button

---

LoadingOverlay

Loading overlay component.

Basic Usage

import {useState} from 'react';
import {PilotKit, LoadingOverlay} from '@bdky/aaas-pilot-kit-react-widget';
import '@bdky/aaas-pilot-kit-react-widget/styles.css';

function App() {
    const [showLoading, setShowLoading] = useState(true);

    return (
        <PilotKit onReady={() => setShowLoading(false)} {...props}>
            <LoadingOverlay
                show={showLoading}
                title="Calling"
                description="Connecting to digital employee..."
                avatar={<img src="/avatar.jpg" alt="" />}
            />
        </PilotKit>
    );
}

Props

Property	Type	Default	Description
show	boolean	false	Whether to show
className	string	-	Custom class name
style	CSSProperties	-	Custom style
backgroundUrl	string	-	Background image URL
title	string	'Calling'	Title
description	string	''	Description text
avatar	ReactNode	-	Avatar element (with breathing animation)

Style Customization

Class Name	Description
.apk-loading-overlay-wrapper	Outer container
.apk-loading-overlay	Inner container (frosted glass effect)
.apk-loading-overlay__content	Content area
.apk-loading-overlay__avatar-wrapper	Avatar wrapper (with pulse animation)
.apk-loading-overlay__avatar-outer	Avatar outer layer
.apk-loading-overlay__text	Title text
.apk-loading-overlay__tip	Description text

Animation

Avatar wrapper has pulse breathing animation, implemented through CSS @keyframes apk-calling-pulse.

---

StatusOverlay

Generic status overlay component, used for displaying busy, timeout, and other states.

Basic Usage

import {useState} from 'react';
import {PilotKit, StatusOverlay} from '@bdky/aaas-pilot-kit-react-widget';
import '@bdky/aaas-pilot-kit-react-widget/styles.css';

function App() {
    const [showBusy, setShowBusy] = useState(false);

    return (
        <>
            {showBusy ? (
                <StatusOverlay
                    show
                    message="Sorry, I'm busy right now, please try again later"
                    buttonText="Call Again"
                    avatar={<img src="/avatar.jpg" alt="" />}
                    backgroundUrl="/background.jpg"
                    onButtonClick={() => setShowBusy(false)}
                />
            ) : (
                <PilotKit onBusy={() => setShowBusy(true)} {...props}>
                    {/* ... */}
                </PilotKit>
            )}
        </>
    );
}

Responsive Adaptation

Feature	PC	Mobile
Content Alignment	Vertical center	Top alignment + padding
Avatar Size	120px	100px
Font Size	16px	14px

Props

Property	Type	Default	Description
show	boolean	false	Whether to show
variant	'auto' | 'mobile' | 'desktop'	'auto'	Display mode
className	string	-	Custom class name
style	CSSProperties	-	Custom style
backgroundUrl	string	-	Background image URL
avatar	ReactNode	-	Avatar element
message	string	-	Status message
buttonText	string	'OK'	Button text
onButtonClick	() => void	-	Button click callback

Custom Rendering

<StatusOverlay show={showStatus}>
    {({avatar, message, buttonText, onButtonClick}) => (
        <div className="my-status">
            <div className="avatar">{avatar}</div>
            <p className="message">{message}</p>
            <button onClick={onButtonClick}>{buttonText}</button>
        </div>
    )}
</StatusOverlay>

Style Customization

Class Name	Description
.apk-status-overlay-wrapper	Outer container
.apk-status-overlay	Inner container (frosted glass effect)
.apk-status-overlay__content	Content area
.apk-status-overlay__avatar-wrapper	Avatar wrapper
.apk-status-overlay__avatar-outer	Avatar outer layer
.apk-status-overlay__message	Status message
.apk-status-overlay__button	Action button

Common Scenarios

// Busy state
<StatusOverlay
    show={isBusy}
    message="Sorry, I'm busy right now, please try again later"
    buttonText="Call Again"
    onButtonClick={handleRetry}
/>

// Timeout state
<StatusOverlay
    show={isTimeout}
    message="This conversation flow has ended, I've hung up"
    buttonText="Start Again"
    onButtonClick={handleRestart}
/>

// Error state
<StatusOverlay
    show={hasError}
    message="Connection failed, please check network and retry"
    buttonText="Retry"
    onButtonClick={handleRetry}
/>

Related

• PilotKit Event Callbacks - onBusy, onInactivity and other events
• Quick Start - Complete example