# JavaScript

Lets you attach custom JavaScript to a page. The script can run on a fixed event (page load, before submit, after submit, item scanned) or as a custom callable, with access to session variables and order data.

This is the escape hatch for behaviour the standard blocks don't support. Use it carefully — script errors break the page, and logic here is harder to maintain than configuration on a real component.

## Available in

* All module types

## When to use

* A bit of glue logic between two existing blocks (e.g. when an item is scanned, also play a confirmation sound).
* Pre-submit validation rules that go beyond what the standard validation provides.
* Post-submit side effects (write a log entry, fire a webhook, update a session variable).
* Hooking into Order Form lifecycle events (item scanned, before submit, after submit) without a custom component.

If your script grows beyond a few dozen lines, consider asking for a dedicated component — long-running JavaScript inside a docs-managed string is fragile.

## Settings

| Setting       | Description                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Configure** | Opens the configuration modal. All script options live here — description, when to execute, action handler, and the JavaScript body. |

The configuration modal supports:

* **Description** — short note about what the script does. Shown in the editor.
* **Execute on** — when the script runs. Two modes:
  * *Auto Run (On Mount)* — the script runs automatically when the page or module loads.
  * *Custom Event* — the script runs when a specific page event fires. After choosing this mode, a second selector appears where you pick the event from a list. Available events depend on which blocks are on your page and the module type — examples include when an item is scanned, before order submission, after a successful submission, after a customer is selected, and more.
* **JS Code** — the JavaScript body, written in a code editor with syntax highlighting and line numbers. Has access to session variables and order context as documented in the modal.

## How it works

The script runs in the page's JavaScript context with access to:

* The session variables system (read and write).
* Order data when the trigger is order-related (e.g. `beforeSubmit`, `itemScanned` provide the relevant payload).

When the configured trigger fires, the script body executes once.

{% hint style="warning" %}
A thrown exception in your script can break the page. Always wrap risky logic in `try/catch` and fail safely (log to console, set a session variable for diagnostics, but don't let the page hang).
{% endhint %}

## Examples

**Sound on scan.** Set *Execute on* to **Custom Event** and pick the item-scanned event from the list. Play an audio tone when the event fires. Cashiers get instant feedback when a scan registers.

**Pre-submit guard.** Set *Execute on* to **Custom Event** and pick the before-submit event. Read a session variable, and if it indicates a hold, abort the submission before it fires.

**Webhook on success.** Set *Execute on* to **Custom Event** and pick the after-submit event. Send the completed order ID to an internal logging endpoint when the submission succeeds.

## Related

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>HTML</strong></td><td>Pair with HTML when you need both markup and logic.</td><td><a href="/pages/eJIk54iTsfwxsVYk4YAF">/pages/eJIk54iTsfwxsVYk4YAF</a></td></tr><tr><td><strong>Variables</strong></td><td>Initialise session variables your script reads.</td><td><a href="/pages/2ToYy14LbRDeVch9XRjC">/pages/2ToYy14LbRDeVch9XRjC</a></td></tr><tr><td><strong>Module Variables</strong></td><td>Reading and setting session variables from script.</td><td><a href="/pages/S9QlmvCWJ8AOsDrFpQtz">/pages/S9QlmvCWJ8AOsDrFpQtz</a></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.in8sync.com/client-admin-guide/active-workflows/getting-started/advanced-components/javascript.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.