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

# Widgets

> This guide will help you understand how to display Axle's embeddable widgets to your users.

Axle widgets are full-viewport overlays that surface additional user experiences within your application, similar to [Axle Ignition](/guides/initialize-ignition). Currently, `validation` is the only supported widget type - it displays a policy's [validation](/guides/validate/policy-validation) result to the user.

## Start a widget session

Once you have a `validationResult` from [Validate Policy](/api-reference/validation/validate-policy), start a widget session using the [Start Widget](/api-reference/widgets/start-widget) endpoint. This returns a `widgetToken` and a `widgetUri` to display to the user.

```bash Request Sample theme={null}
curl --request POST \
  --url https://sandbox.axle.insure/widgets \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: cli_mZj6YGXhQyQnccN97aXbq' \
  --header 'x-client-secret: RZM-5BErZuChKqycbCS1O' \
  --data '{
  "validation": {
    "enabled": true,
    "data": {
      "validationResult": "val_abcdef123456"
    }
  }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "widgetToken": "ey...",
    "widgetUri": "https://widget.sandbox.axle.insure/?token=ey..."
  }
}
```

## Appending origin or redirect URI

Before rendering the widget, your application should append either `origin` (for web) or `redirectUri` (for mobile) as a query parameter to the `widgetUri`. This tells the widget how to communicate back to your application on exit.

**Web:**

```
https://widget.sandbox.axle.insure/?token=ey...&origin=https://example.com
```

**Mobile:**

```
https://widget.sandbox.axle.insure/?token=ey...&redirectUri=https://example.com/validation/redirect
```

## Web: Display in iframe

<Steps>
  <Step title="Open iframe">
    Render the `widgetUri` (with `origin` appended) in an iframe set to 100% width and 100% height of the viewport. Axle handles all internal layout and scrolling, so your application doesn't need to manage the widget's sizing.
  </Step>

  <Step title="Listen for MessageEvent">
    Add an event listener on the parent window. For security, verify that the message origin is the Axle widget domain (e.g., `https://widget.sandbox.axle.insure`) before processing.
  </Step>

  <Step title="Process the exit event">
    When the user closes or exits the widget, remove the iframe (or close the modal) and return the user to the previous view.
  </Step>
</Steps>

```HTML Page with iframe and eventListener (example) theme={null}
<style>
  .validation-widget {
    z-index: 999;
    position: fixed;
    left: 0;
    top: 0;
    height: 100%;
    width: 100%;
    border: none;
  }
</style>

<iframe
  src="https://widget.sandbox.axle.insure/?token=ey...&origin=https://example.com"
  class="validation-widget"
></iframe>

<script>
  window.addEventListener("message", (event) => {
    if (event.origin === "https://widget.sandbox.axle.insure") {
      switch (event.data.status) {
        case "exit":
          // Remove the iframe / close the modal
          break;
      }
    }
  });
</script>
```

## Mobile: Display in native webview

Open the `widgetUri` (with `redirectUri` appended) in a native webview. When the user exits the widget, Axle redirects to the `redirectUri` you provided with a `status` query parameter appended:

```
https://example.com/validation/redirect?status=exit
```

Your native app should catch this redirect and close the webview.

## Widget events

| Platform         | Delivery                              | Requires                              |
| ---------------- | ------------------------------------- | ------------------------------------- |
| Web (iframe)     | `window.postMessage` to parent window | `origin` appended to `widgetUri`      |
| Mobile (webview) | URL redirect                          | `redirectUri` appended to `widgetUri` |

### onExit

Emitted when the user closes or exits the widget (e.g., clicks a close button or back action).

**Via `postMessage` (web):**

```json theme={null}
{
  "status": "exit"
}
```

**Via redirect (mobile):**

```
{redirectUri}?status=exit
```

When your application receives this event, it should tear down the iframe or close the webview and return the user to the previous view.

<Check>
  That's it - your users can now view their validation result through Axle's widget without leaving your application 🎉.
</Check>