---
title: "AgentScreen"
description: "A fixed-ratio frame that shows what an agent is looking at."
category: AiAgent
status: beta
since: 0.6.0
tags: [agent, screen, capture, ai]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
`state` switches between the capture and a placeholder; `cursor` overlays a pointer with an action label.
:::TuffDemoWrapper{demo="AgentScreenAgentScreenDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const state = ref<'working' | 'loading'>('working')
  </script>

  <template>
    <TxAgentScreen
      :state="state"
      label="Agent's screen"
      :cursor="{ x: 46, y: 62, label: 'Opening Photos' }"
    >
      <!-- A screenshot, a canvas, or a video -->
      <canvas ref="surface" />
    </TxAgentScreen>
  </template>
---
:::

### Best Practices

- Put a live canvas or video in the default slot; keep `src` for static captures.
- Let `label` say whose screen it is, and the pointer's `label` say what the agent is doing.
- Between frames, set `state` to `loading` instead of leaving a stale frame up; a stale frame reads as stuck.

## API Reference

### Props

| Name | Type | Default | Description |
|---|---|---|---|
| `src` | `string` | - | Image source; ignored when the default slot is filled. |
| `alt` | `string` | - | Accessible description of the capture; required whenever `src` is set. |
| `label` | `string` | - | Caption under the frame; omit to render none. |
| `state` | `'working' \| 'loading'` | `'working'` | Shows the capture or the loading placeholder. |
| `cursor` | `AgentScreenCursor` | - | Pointer overlay; omit to hide it. |
| `ratio` | `string` | `'2964 / 1856'` | CSS `aspect-ratio` of the frame; defaults to the upstream capture's ratio. |
| `ariaLabel` | `string` | `'Agent screen'` | Accessible name of the whole region. |
| `loadingLabel` | `string` | `'Waiting for the agent’s screen'` | Announced while loading. |

### Slots

| Name | Description |
|---|---|
| `default` | Replaces the frame content; takes precedence over `src`. |
| `overlay` | Above the content, inside the clip; dropped while loading. |
| `label` | Replaces the caption under the frame. |

### Types

#### AgentScreenCursor

| Field | Type | Description |
|---|---|---|
| `x` / `y` | `number` | Percent of the frame (0–100), so the point holds at any size; out-of-range values are clamped. |
| `label` | `string` | A line beside the pointer, usually the current action. |

## Overview

- The component owns the frame, the pointer, and the caption; the content comes from the default slot or `src`, never both.
- `ratio` fixes the proportions, not the height: the width follows the container.
- When `state` is `loading`, or there is neither a default slot nor `src`, a skeleton placeholder replaces the capture, the pointer, and `overlay`.
- The root is a `role="group"` named by `ariaLabel`; the placeholder is a `role="status"` with `aria-live="polite"` that announces `loadingLabel`.
- Under reduced motion, the placeholder stops shimmering.

## Technologies

- The placeholder reuses the library's `skeleton-surface` bar, tinted to the BUI surface color.
- Adapted from [Beautiful UI](https://www.beautifului.dev) case 21, Agent Screen (© 2026 Shane Levine, MIT).
- Source: `packages/tuffex/packages/components/src/agent-screen/`.

<TuffDocSourceLink />