> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ready-made screens

> @streampixel/ui draws the screens around the video for the Streampixel Web SDK: loading, password, click to start, idle warning, text input, files, links, controls and the end message. Switch one off, restyle it, or replace it with your own.

Intermediate For web developers who want a complete viewer experience without drawing every screen. After this page you can mount the screens, switch any of them off, restyle them, and replace one with your own.

The SDK draws the video and nothing else. `@streampixel/ui` draws everything a viewer sees around it. It is plain DOM inside your container, with no framework.

> [!NOTE]
>
> `@streampixel/ui` is an npm package. It is not in the script-tag build. Unlike the stream engine, these screens are part of the package you install: a fix to them needs a new install.

## Mount the screens

**1. Install**

```bash npm theme={"dark"}
npm install @streampixel/web-sdk @streampixel/ui
```

```bash yarn theme={"dark"}
yarn add @streampixel/web-sdk @streampixel/ui
```

```bash pnpm theme={"dark"}
pnpm add @streampixel/web-sdk @streampixel/ui
```

**2. Mount right after create()**

```ts highlight={12} theme={"dark"}
import { Streampixel } from '@streampixel/web-sdk';
import { mountUI, type MountedUI } from '@streampixel/ui';

const container = document.getElementById('stream')!;
let stream: Streampixel | undefined;
let ui: MountedUI | undefined;

async function start() {
  ui?.destroy();       // the screens first, then the stream
  stream?.destroy();
  stream = await Streampixel.create({ appId: 'YOUR_PROJECT_ID', container });
  ui = mountUI(stream, { container, onRestart: start }); // "Start again" on the end message
}
start();
```

Pass the same element as the stream's `container`: the screens go on top of the video.

> [!TIP]
>
> You see the loading screen with your project's logo and loading texts, then your app with a control bar at the bottom right.

**3. Remove them in the right order**

`mountUI()` returns an object with one method, `destroy()`. Call `ui.destroy()` before `stream.destroy()`, when you tear down and when you start again.

The logo, the banner and the loading texts come from the project's settings in the dashboard: see [Branding](https://docs.streampixel.io/resources/dashboard/branding.md).

### Mounting later

Mount the screens right after `create()` resolves. They can also be mounted later: `mountUI()` shows the screen for the state the stream is in at that moment.

| Stream state when mounted | Shown |
| - | - |
| `awaitingPassword` (a password project) | The password screen |
| `idle`, `connecting`, `queued`, `reconnecting`, `recovering` | The loading screen |
| `streaming` | Nothing over the video, and the control bar |
| `awaitingPlay` | "Click to start" |
| `ended` | The end message |

## The screens

Ten parts, all on by default. Each has an option of the same name that switches it off.

| Option | Shown when | In short |
| - | - | - |
| `loading` | Until the video plays, and again while reconnecting or restarting | Logo, banner, spinner, loading texts, status line, queue position |
| `password` | The state is `awaitingPassword` | "This stream is protected", a password field, Continue |
| `playPrompt` | The state is `awaitingPlay` | "Ready to start" and a "Click to start" button |
| `afk` | The idle countdown runs | "Are you still there?", the seconds left, "I'm still here" |
| `osk` | Your app asks for text input | A text field with Send and Cancel |
| `files` | Your app sends a file | Progress, then the file is saved (a Save button on phones and tablets) |
| `links` | Your app sends an `https` link | Opened in a new tab (an Open button on phones and tablets) |
| `tcpToast` | UDP is blocked and the stream is relayed over TCP | A notice, once |
| `controls` | Once the video plays | Sound, stream information, fullscreen |
| `disconnect` | The state is `ended` | The end message and one button |

Open a part for its exact behaviour and wording.

> [accordion] loading: the loading screen
>
> Shown until the video plays, and again while the stream reconnects or restarts.
>
> | Element | Content |
> | - | - |
> | Background | The project's loading banner: an image, or an `.mp4` or `.webm` video. None when the project has no banner. |
> | Logo | The project's logo. None when the project has no logo. |
> | Loading text | The project's loading text one when your app answers, text two when the browser's answer goes back, text three when the connection is up. "Preparing your stream…" when the project has no texts. |
> | Status line | "Connecting…", "Reconnecting…", "Restarting the stream…", or "Waiting for the host to reconnect…" for a viewer of a shared session. |
> | Queue | "You are in queue" and the position. |
>
> In a [Test locally](https://docs.streampixel.io/resources/web-sdk-v2/test-locally.md) session the status line says "Waiting for your Unreal Editor…" while it connects, and "Waiting for your Unreal Editor to come back…" while it reconnects.
>
> With `disconnect: false`, this screen also shows the end message.

> [accordion] password: the password screen
>
> Shown while the stream is in the state `awaitingPassword`: the project's logo, "This stream is protected", a password field and Continue.
>
> | State of the stream | The screen |
> | - | - |
> | `awaitingPassword` | An empty field and Continue. |
> | `wrong: true` | "Incorrect password. Please try again." |
> | `locked: true` without `hard` (too many wrong attempts; the right password is still accepted) | "Too many incorrect attempts. Check the password and try again." **The field stays usable.** |
> | `hard: true` with `retryAfterSec` (every attempt is refused for now) | "Too many attempts. Try again in N seconds." (or minutes), counting down. The form is disabled until the time is over, then enabled again. |
> | `hard: true` without a time | "Too many attempts. Please try again later." |
> | `submitPassword()` rejected: network | "Could not reach the server. Check your connection and try again." |
> | `submitPassword()` rejected: project offline | "This stream is unavailable right now." |
> | `submitPassword()` rejected: anything else | "Something went wrong on our side. Please try again in a moment." |
>
> The field is cleared after every attempt. The package never keeps the typed password. See [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md) for how password projects work.

> [accordion] playPrompt: click to start
>
> Shown while the state is `awaitingPlay`: the stream is up, and the browser refused to start the video without a click. The card says "Ready to start" and "Your browser paused the stream.", with a "Click to start" button that calls `stream.play()`.

> [accordion] afk: the idle warning
>
> Shown while the idle countdown runs: "Are you still there?", "No activity detected", the seconds left, and an "I'm still here" button. The button cancels the countdown. When the countdown reaches zero, the session ends and the end message says so.

> [accordion] osk: text input for phones
>
> Shown when your app asks for text input (a text field in your app got focus). The card says "Enter text" and has a text field with what your app's field already holds, Send and Cancel. Enter sends, Escape closes. The card also closes when your app asks to hide the keyboard.

> [accordion] files: files your app sends
>
> While a file arrives, a notice shows its progress in percent.
>
> | Device | When the file is complete |
> | - | - |
> | Desktop | The file is saved at once. |
> | Phones and tablets | A notice with a Save button. Where the device can share files, the button opens the system share sheet. Otherwise it downloads the file. |
>
> See [Send files to the viewer](https://docs.streampixel.io/resources/additional-unreal-engine-features/send-files-to-the-viewer.md) for the Unreal side.

> [accordion] links: links your app sends
>
> Shown when your app sends a plain `https` link.
>
> | Device | What happens |
> | - | - |
> | Desktop | The link opens in a new tab at once. |
> | Phones and tablets | A card, "Leaving the stream", with an "Open" button per link (up to three) and "Stay here". Phones need a tap before they open a tab. |

> [accordion] tcpToast: the UDP warning
>
> Shown once, when UDP is blocked on the viewer's network and the stream is relayed over TCP, which reduces quality. The notice stays for 15 seconds, or until the viewer clicks it. It appears only when the project's "UDP blocked warning" setting is on.

> [accordion] controls: the control bar
>
> Shown once the video plays, at the bottom right of the container. Three buttons:
>
> | Button | Does |
> | - | - |
> | Sound | Turns the sound on or off. Streams start muted. |
> | Stream information | A popup with live values: frame rate, round-trip time, resolution, codec, bitrate, relay, dropped frames. |
> | Fullscreen | Puts the container in fullscreen, and leaves it. |

> [accordion] disconnect: the end message
>
> Shown when the state is `ended`: a title, the sentence from `ended.message`, and one button.
>
> | Title | When |
> | - | - |
> | "Session ended" | The session ended for inactivity (`endKind: 'afk'`). |
> | "Network blocked" | The viewer's network blocks the stream (`endKind: 'network-blocked'`). |
> | "Reconnection failed" | Code `4007`. |
> | "Disconnected" | Every other end. |
>
> | `onRestart` | Button | Does |
> | - | - | - |
> | Given | "Start again" | Calls your function. Destroy this UI and stream there and start new ones, as in the example above. |
> | Not given | "Reload" | Reloads the page. |
>
> When the stream ends, the idle warning, the text-input card and the file and link cards close, so nothing stays on top of the end message.

## Options

`mountUI(stream, options)` takes these options.

**container** `HTMLElement` *required*

Where the screens go: the stream's container.

**loading, password, playPrompt, afk, osk, files, links, tcpToast, controls, disconnect** `boolean` (default: true)

`false` switches that part off. See [The screens](#the-screens).

**accentColor** `string` (default: #4e9cff)

The colour of buttons, the spinner and badges. It is inserted into CSS: pass a colour you control, never user input.

**onRestart** `() =\> void`

What the button on the end message does. Without it, the button reloads the page.

`mountUI()` returns a `MountedUI`:

**destroy** `() =\> void`

Removes every screen this call added. Call it before `stream.destroy()`.

## Switch a screen off

Set its option to `false`.

```ts theme={"dark"}
const ui = mountUI(stream, {
  container,
  controls: false, // no control bar
  tcpToast: false, // no UDP warning
});
```

> [!WARNING]
>
> A part you switch off is not replaced by anything. Without `playPrompt`, a viewer whose browser blocks autoplay sees a paused video and no hint to click it. Without `afk`, an idle viewer is disconnected with no warning. Switch a part off when you do not need it, or when you draw your own.

With `files` or `links` switched off, the SDK's own default applies again: desktop browsers download the file or open the link, and phones and tablets do nothing.

## Restyle the screens

### The accent colour

```ts theme={"dark"}
const ui = mountUI(stream, { container, accentColor: '#ff6a00' });
```

If you mount several UIs on one page, they share one set of styles, and the accent colour comes from the UI that was mounted first.

### Your own CSS

Every element has a class that starts with `spx-`. Override the classes in your own stylesheet.

```css styles.css theme={"dark"}
/* Start each selector with your container: see the note below. */
#stream .spx-btn {
  border-radius: 999px;
  font-weight: 600;
}

#stream .spx-overlay {
  font-family: 'Inter', system-ui, sans-serif;
}

#stream .spx-bar {
  right: auto;
  left: 14px; /* the control bar on the left */
}
```

> [!NOTE]
>
> The package adds its styles to the end of `<head>` when you mount, so they come after your stylesheet. A rule of yours with the same selector would lose. Start your selectors with your container (`#stream .spx-btn`), which makes them more specific.

> [accordion] All classes
>
> | Class | Element |
> | - | - |
> | `spx-overlay` | A full-size screen: loading, password, end message. The loading screen also has the attribute `data-spx="loading"`, the password screen `data-spx="password"`. |
> | `spx-logo` | The project's logo. |
> | `spx-spinner` | The spinner on the loading screen. |
> | `spx-sub` | The loading text, and the sentence on the end message. |
> | `spx-status` | The status line on the loading screen. |
> | `spx-queue`, `spx-queue-badge` | The queue line and its position badge. |
> | `spx-title` | The title on the end message. |
> | `spx-card-overlay` | The dimmed layer behind a card: click to start, idle warning, text input, links. |
> | `spx-card` | A card. |
> | `spx-count` | The seconds on the idle warning. |
> | `spx-btn`, `spx-btn-dim` | A button, and a secondary button. |
> | `spx-input` | A text field. |
> | `spx-pw-form`, `spx-err` | The password form and its error line. |
> | `spx-bar` | The control bar. |
> | `spx-pop` | The stream information popup. |
> | `spx-toast` | A notice at the top: the UDP warning, a file's progress. |
>
> The layers, from back to front: full-size screens (`z-index` 40), the control bar (50), the information popup (55), cards (60), notices (70).

The wording is English and fixed. To change a text, replace that part.

## Replace one screen with your own

Switch the part off, and draw your own from the SDK's states and events. The other parts keep working.

This example replaces "Click to start" with a button of your own. The button sits next to the container, in a wrapper, and above the video:

```ts main.ts theme={"dark"}
import { mountUI } from '@streampixel/ui';
import type { Streampixel, StreamState } from '@streampixel/web-sdk';

export function mountScreens(stream: Streampixel, container: HTMLElement) {
  const startButton = document.getElementById('my-start') as HTMLButtonElement;

  const ui = mountUI(stream, {
    container,
    playPrompt: false, // you draw "Click to start"
  });

  // Show your button while the browser waits for a click.
  const render = (state: StreamState) => {
    startButton.hidden = state.kind !== 'awaitingPlay';
  };
  render(stream.state);
  stream.on('state', render);

  startButton.onclick = () => stream.play();

  return ui;
}
```

```html index.html theme={"dark"}
<div style="position: relative; width: 100%; height: 100vh">
  <div id="stream" style="width: 100%; height: 100%"></div>
  <button id="my-start" hidden
          style="position: absolute; inset: 0; margin: auto; width: 12em; height: 3em; z-index: 45">
    Start the experience
  </button>
</div>
```

What each part is built from:

| Part | SDK states, events and methods |
| - | - |
| `loading` | `state`, `progress`, `queue`, `stream.streamConfig` (the branding) |
| `password` | the state `awaitingPassword`, `stream.submitPassword()` |
| `playPrompt` | the state `awaitingPlay`, `stream.play()` |
| `afk` | `afkWarning`, `stream.keepAlive()` |
| `osk` | `osk`, `oskHide`, `stream.sendTextboxEntry()` |
| `files` | `fileProgress`, `file` |
| `links` | `openUrl` |
| `tcpToast` | `relayFallback` |
| `controls` | `stream.toggleAudio()`, `stats` |
| `disconnect` | `ended` |

Two parts need care when you replace them:

| Replacing | Know this |
| - | - |
| `password` | With `password: false` and `loading` on, the loading screen stays up while the stream waits for the password. Draw your form above it (the loading screen has `z-index: 40`), or outside the container. |
| `disconnect` | With `disconnect: false` and `loading` on, the loading screen shows the end message. Draw your own end screen above it, or call `ui.destroy()` when `ended` fires and then show yours. |

Complete recipes for your own loading screen, queue display, idle warning and more are in the [Cookbook](https://docs.streampixel.io/resources/web-sdk-v2/cookbook.md). The states and events are in [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md).

## What it does to your page

| Fact | Detail |
| - | - |
| Container | Sets `position: relative` on the container when it is `static`. `destroy()` does not set it back. |
| Styles | Adds one `<style id="spx-ui-styles">` element to `<head>`. Every mounted UI shares it, and it is removed when the last one is destroyed. A Content-Security-Policy with a strict `style-src` must allow this element. |
| Images | Loads the project's logo and banner from the addresses set in the dashboard. A Content-Security-Policy must allow those hosts in `img-src`, and in `media-src` for a video banner. |
| Events | With `files` or `links` on, the package handles those events, so the SDK's own default (download or open on desktop, nothing on phones) no longer applies. |

## What it does not have

| Not in this package | What to do |
| - | - |
| Screens before a stream exists: "project offline", "project not found", "sign-in failed" | `mountUI()` needs a stream, and in these cases `create()` rejects. Draw them yourself: the `AuthError` carries the project's `branding`. See [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md). |
| A resolution picker, an XR button, microphone and camera buttons | Build them with the stream's methods: see [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md). |
| A chat panel | Build it with [Voice chat](https://docs.streampixel.io/resources/web-sdk-v2/voice-chat.md). |
| The dashboard's settings for logo position, loading type, and showing or hiding single control buttons | They are not read. |
| Other languages, or other wording | The text is English and fixed. Replace the part. |

## Next steps

> [card] [Cookbook](https://docs.streampixel.io/resources/web-sdk-v2/cookbook.md)
>
> Your own loading screen, queue display, idle warning and more.

> [card] [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md)
>
> One level up: everything the screens are built from.

> [card] [Controls and input](https://docs.streampixel.io/resources/web-sdk-v2/controls-and-input.md)
>
> Sound, resolution, fullscreen and input, for your own control bar.

> [card] [Access](https://docs.streampixel.io/resources/web-sdk-v2/access.md)
>
> Password, single sign-on and your own password form.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.