> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mercuryworkshop/scramjet/llms.txt
> Use this file to discover all available pages before exploring further.

# ScramjetFrame

> Abstraction for managing proxy iframes

The `ScramjetFrame` class provides an abstraction over proxy iframe creation and management. It handles navigation, event dispatching, and provides access to the proxified context.

## Constructor

Creates a new `ScramjetFrame` instance.

```typescript theme={null}
new ScramjetFrame(
  controller: ScramjetController,
  frame: HTMLIFrameElement
)
```

<ParamField path="controller" type="ScramjetController" required>
  The `ScramjetController` instance that manages this frame
</ParamField>

<ParamField path="frame" type="HTMLIFrameElement" required>
  The iframe element to be controlled under Scramjet
</ParamField>

<Note>
  You typically won't call this constructor directly. Use `ScramjetController.createFrame()` instead.
</Note>

### Example

```typescript theme={null}
const { ScramjetController } = $scramjetLoadController();
const scramjet = new ScramjetController({ prefix: "/scramjet/" });
await scramjet.init();

const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);
frame.go("https://example.com");
```

## Properties

### frame

The underlying `HTMLIFrameElement` being managed.

```typescript theme={null}
frame: HTMLIFrameElement
```

#### Example

```typescript theme={null}
const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);
frame.frame.style.width = "100%";
frame.frame.style.height = "600px";
```

### client

Returns the `ScramjetClient` instance running inside the iframe's contentWindow.

```typescript theme={null}
get client(): ScramjetClient
```

#### Returns

The `ScramjetClient` instance for the iframe's context.

#### Example

```typescript theme={null}
const client = frame.client;
console.log("Current URL:", client.url);
```

### url

Returns the proxified URL as a `URL` object.

```typescript theme={null}
get url(): URL
```

#### Returns

The current proxified URL.

#### Example

```typescript theme={null}
console.log("Current URL:", frame.url.href);
console.log("Hostname:", frame.url.hostname);
```

## Methods

### go()

Navigates the iframe to a new URL under Scramjet.

```typescript theme={null}
go(url: string | URL): void
```

<ParamField path="url" type="string | URL" required>
  A real URL to navigate to
</ParamField>

#### Example

```typescript theme={null}
frame.go("https://example.net");
frame.go(new URL("https://example.org"));
```

### back()

Goes backwards in the browser history.

```typescript theme={null}
back(): void
```

#### Example

```typescript theme={null}
frame.back();
```

### forward()

Goes forward in the browser history.

```typescript theme={null}
forward(): void
```

#### Example

```typescript theme={null}
frame.forward();
```

### reload()

Reloads the iframe.

```typescript theme={null}
reload(): void
```

#### Example

```typescript theme={null}
frame.reload();
```

### addEventListener()

Binds event listeners to listen for proxified navigation events in Scramjet.

```typescript theme={null}
addEventListener<K extends keyof ScramjetEvents>(
  type: K,
  listener: (event: ScramjetEvents[K]) => void,
  options?: boolean | AddEventListenerOptions
): void
```

<ParamField path="type" type="'navigate' | 'urlchange' | 'contextInit'" required>
  Type of event to listen for
</ParamField>

<ParamField path="listener" type="Function" required>
  Event listener callback function
</ParamField>

<ParamField path="options" type="boolean | AddEventListenerOptions">
  Options for the event listener
</ParamField>

#### Example

```typescript theme={null}
// Listen for URL changes
frame.addEventListener("urlchange", (event) => {
  console.log("URL changed:", event.url);
  document.title = event.url; // Update page title
});

// Listen for navigation events
frame.addEventListener("navigate", (event) => {
  console.log("Navigating to:", event.url);
});

// Listen for context initialization
frame.addEventListener("contextInit", (event) => {
  console.log("Scramjet initialized in frame");
});
```

## Events

### navigate

Fired when the frame navigates to a new proxified URL.

```typescript theme={null}
class NavigateEvent extends Event {
  type: "navigate";
  url: string;
}
```

### urlchange

Fired when the proxified URL changes in the frame.

```typescript theme={null}
class UrlChangeEvent extends Event {
  type: "urlchange";
  url: string;
}
```

### contextInit

Fired when Scramjet initializes in the frame.

```typescript theme={null}
class ScramjetContextEvent extends Event {
  type: "contextInit";
  window: Self;
  client: ScramjetClient;
}
```

See [event types](/api/event-types) for complete event definitions.

## Complete example

```typescript theme={null}
const { ScramjetController } = $scramjetLoadController();

const scramjet = new ScramjetController({ prefix: "/scramjet/" });
await scramjet.init();

const frame = scramjet.createFrame();
document.body.appendChild(frame.frame);

// Listen for proxified navigation events
frame.addEventListener("urlchange", (e) => {
  console.log("URL changed to:", e.url);
});

// Navigate to a URL
frame.go("https://example.com");

// Control navigation
frame.back();
frame.forward();
frame.reload();
```