# Overlays and UI Components

## Built-In Overlays

The SDK includes several overlay components inherited from the Epic Games Pixel Streaming UI library:

| Overlay             | Purpose                                                  |
| ------------------- | -------------------------------------------------------- |
| `ConnectOverlay`    | Shown during initial connection                          |
| `DisconnectOverlay` | Shown when the stream disconnects, with reconnect option |
| `AFKOverlay`        | Shown during AFK warning countdown                       |
| `PlayOverlay`       | Shown before the stream starts (click to play)           |
| `InfoOverlay`       | Generic information text display                         |
| `ErrorOverlay`      | Error messages                                           |

These overlays are part of the Pixel Streaming UI library and can be imported directly:

```javascript
import {
  ConnectOverlay,
  DisconnectOverlay,
  AFKOverlay,
  PlayOverlay,
  InfoOverlay,
  ErrorOverlay,
  OverlayBase,
  ActionOverlay,
  TextOverlay,
} from 'streampixelsdk';
```

## Hiding Default Overlays

{% hint style="info" %}
Most applications replace the default overlays with custom UI. The built-in overlays are useful for prototyping, but you will typically hide them and build your own for production.
{% endhint %}

Most applications replace the default overlays with custom UI. Hide them with CSS:

```css
/* Hide all default Pixel Streaming UI */
#uiFeatures {
  display: none !important;
}

/* Hide specific overlays */
#afkOverlay {
  display: none !important;
}

#connectOverlay {
  display: none !important;
}

#infoOverlay {
  display: none !important;
}
```

Or programmatically:

```javascript
// After initialization
const uiFeatures = appStream.uiFeaturesElement
  || appStream.rootElement?.querySelector('#uiFeatures');
if (uiFeatures) uiFeatures.style.display = 'none';
```

## Showing Overlays Programmatically

The SDK provides methods to show overlays:

```javascript
// Show the disconnect overlay with a custom message
appStream.showDisconnectOverlay('Connection lost. Click to reconnect.');

// Show a text overlay
appStream.showTextOverlay('Loading...');
```

## Building Custom UI

Instead of using the built-in overlays, build your own UI components and drive them with SDK events. This gives you full control over appearance and behavior.

### Custom Controls Toolbar

```html
<div id="controls" style="position: fixed; bottom: 20px; right: 20px; display: flex; gap: 8px;">
  <button id="mute-btn">Unmute</button>
  <button id="fullscreen-btn">Fullscreen</button>
  <button id="stats-btn">Stats</button>
</div>
```

{% code lineNumbers="true" %}

```javascript
// Mute/Unmute
let muted = true;
document.getElementById('mute-btn').addEventListener('click', () => {
  muted = !muted;

  const video = appStream.stream.videoElementParent.querySelector('video');
  const audio = appStream.stream._webRtcController?.streamController?.audioElement;

  if (video) video.muted = muted;
  if (audio) {
    audio.muted = muted;
    if (!muted && audio.paused) audio.play().catch(() => {});
  }

  document.getElementById('mute-btn').textContent = muted ? 'Unmute' : 'Mute';
});

// Fullscreen
document.getElementById('fullscreen-btn').addEventListener('click', () => {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else {
    document.exitFullscreen();
  }
});

// Stats
document.getElementById('stats-btn').addEventListener('click', () => {
  const stats = UIControl.getStreamStats();
  console.log(stats);
});
```

{% endcode %}

### Custom AFK Warning

See [AFK (Idle Timeout)](https://docs.streampixel.io/resources/getting-started/features/afk-idle-timeout) for a complete custom AFK overlay example.

### Custom Loading Screen

See [Custom Loading Screen](https://docs.streampixel.io/resources/getting-started/ui-and-customization/custom-loading-screen) for building a loading screen driven by lifecycle events.

## CSS Class Reference (from Example App)

The example app uses these CSS classes that you can reference or adapt:

### Loading Screen

* `.loading-overlay` — Full-screen loading container
* `.loading-spinner` — CSS spinner animation
* `.loading-title` — Main heading
* `.loading-subtitle` — Description text
* `.loading-progress-track` — Progress bar track
* `.loading-progress-fill` — Progress bar fill (animated width)
* `.loading-status` — Current status message
* `.loading-queue` — Queue position container
* `.loading-queue-badge` — Queue position number badge

### Stream Controls

* `.stream-controls` — Controls container (fixed, bottom-right)
* `.control-btn` — Individual control button
* `.control-btn-active` — Active state for toggle buttons

### Stats Popup

* `.stats-popup` — Stats panel container
* `.stats-row` — Individual stat row
* `.stats-label` — Stat name
* `.stats-value` — Stat value

### AFK Warning

* `.afk-overlay` — Full-screen AFK backdrop
* `.afk-card` — Warning card
* `.afk-countdown` — Countdown number
* `.afk-btn` — Dismiss button

### Settings

* `.settings-popup` — Settings panel
* `.settings-option` — Individual option
* `.settings-option-active` — Currently selected option

### Developer Tools

* `.dev-tools-popup` — Dev tools panel
* `.dev-tools-section` — Grouped section
* `.dev-tools-input` — Text input field
* `.dev-tools-btn` — Action button