# Web frame

> A sandboxed web page shown by a web widget, exchanging messages only with its declared origin.

Source: https://docs.tune.toys/nodes/web.frame/

Web frame puts a third-party web page inside your Frame through a `web` widget, and lets the Patch and the page exchange messages.

## What it does

The node's `url` field names the page and its `origin` field the one exact origin (such as `https://example.org`) it may talk to. A `web` widget bound to the node shows the page in a sandboxed iframe: scripts and forms may run, but the page gets no access to Tune.Toys, its cookies or the Toy. Messages cabled into `message` are posted to the page with the declared origin as target; messages from the page arrive on `message` only when they come from that origin. A string on `navigate` moves the frame to another URL on the same origin. `state` reports `attached`, `send-only`, `navigating`, `detached` or `refused-message`.

A Toy with a Web frame requires embedding, shown as a chip on the Play surface. Sites that refuse framing show that state rather than a blank box. Screenshots and recordings capture an embed as the browser shows it; nothing bypasses its sandbox.

## When to use it

Use it to place a map, a score viewer, a visualizer you host yourself or another web tool next to your controls, and to steer it from data.

## Ports

<!-- ports:start -->

| Port       | Direction | Signal        | Lanes |
| ---------- | --------- | ------------- | ----- |
| `message`  | Input     | Data (any)    | 1     |
| `navigate` | Input     | Data (string) | 1     |
| `message`  | Output    | Data (json)   | 1     |
| `state`    | Output    | Data (string) | 1     |

<!-- ports:end -->

## Parameters

<!-- parameters:start -->

| Parameter       | Label         | Range  | Default | Unit | Scale  | Notes                                                                       |
| --------------- | ------------- | ------ | ------- | ---- | ------ | --------------------------------------------------------------------------- |
| `load_on_click` | Load on click | 0 to 1 | 1       |      | linear | Wait for a click before loading the third-party page. Choices: 0 Off, 1 On. |

<!-- parameters:end -->

<!-- data:start -->

- `url`: url.
- `origin`: origin.
- `allow`: strings.

<!-- data:end -->

### Load on click (`load_on_click`)

On waits for a click before contacting the third-party site, so opening a Toy never loads someone else's page by surprise. Off loads it with the Frame.

### URL, origin and allow

`url` is the page (`https:`), `origin` the exact origin for messages and navigation, and `allow` grants up to seven browser features from a closed list (autoplay, camera, clipboard-write, fullscreen, geolocation, microphone, midi). Grant only what the page needs.

## Tips

- The widget and the node are one pair: place a `web` widget in the Frame and bind it to the node's port.
- Messages are JSON; agree on a small message shape with the page you embed.

## See also

[Web request](https://docs.tune.toys/nodes/web.request/), [Console log](https://docs.tune.toys/nodes/log.console/), [Frames](https://docs.tune.toys/concepts/frames/), [Data cables](https://docs.tune.toys/concepts/data-cables/).