# Actions

This page is the action index. Use it to see which actions are supported in the current browser runtime and then click through to the detailed action pages.

## What Actions Are

Actions are browser-side workflow steps processed by the BetterForms actions queue.

Use them to:

* navigate or open UI elements
* run browser-side JavaScript
* trigger named actions
* call FileMaker through actions such as `runUtilityHook`

Actions are not the same thing as FileMaker hooks. Hooks are server-side scripts; actions are client-side workflow steps that may call those hooks.

## Core Actions

| Action                            | Summary                                                              | Details                                                                                         |
| --------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `showModal` / `hideModal`         | Opens or closes the standard modal dialog                            | [showModal / hideModal](/reference/actions-processor/actions_overview/showmodal.md)             |
| `showCardModal` / `hideCardModal` | Opens or closes a card modal that renders another page               | [showCardModal / hideCardModal](/reference/actions-processor/actions_overview/showcardmodal.md) |
| `showAlert`                       | Shows a toaster-style alert                                          | [showAlert](/reference/actions-processor/actions_overview/showalert.md)                         |
| `path`                            | Navigates to another page, URL, or target window                     | [path](/reference/actions-processor/actions_overview/path.md)                                   |
| `runUtilityHook`                  | Calls the scoped server utility hook workflow                        | [runUtilityHook](/reference/actions-processor/actions_overview/runutilityhook.md)               |
| `runOnCompleteHook`               | Triggers the completion hook flow and waits before continuing        | [runOnCompleteHook](/reference/actions-processor/actions_overview/runoncompletehook.md)         |
| `validate`                        | Runs page validation                                                 | [validate](/reference/actions-processor/actions_overview/validate.md)                           |
| `setFocus`                        | Focuses or selects an input element                                  | [setFocus](/reference/actions-processor/actions_overview/setfocus.md)                           |
| `scrollTo`                        | Scrolls to a target element                                          | [scrollTo](/reference/actions-processor/actions_overview/scrollto.md)                           |
| `wait`                            | Delays the next queued action for a specified number of milliseconds | [wait](/reference/actions-processor/actions_overview/wait.md)                                   |
| `debounce`                        | Delays repeated actions until activity settles                       | [debounce](/reference/actions-processor/actions_overview/debounce.md)                           |
| `throttle`                        | Limits how frequently an action can run                              | [throttle](/reference/actions-processor/actions_overview/throttle.md)                           |
| `function`                        | Runs JavaScript in the client workflow                               | [function](/reference/actions-processor/actions_overview/function-1.md)                         |
| `emit`                            | Emits an internal event-bus event                                    | [emit](/reference/actions-processor/actions_overview/emit.md)                                   |
| `mapInfoWindow`                   | Emits a component-facing map info-window event                       | [mapInfoWindow](/reference/actions-processor/actions_overview/mapinfowindow.md)                 |
| `clipboard`                       | Interacts with the clipboard helper                                  | [clipboard](/reference/actions-processor/actions_overview/clipboard.md)                         |
| `cookie`                          | Sets or removes browser-side cookies                                 | [cookie](/reference/actions-processor/actions_overview/cookie.md)                               |
| `consoleError`                    | Writes a message to the browser error console                        | [consoleError](/reference/actions-processor/actions_overview/consoleerror.md)                   |
| `namedAction`                     | Runs another named action / workflow by name                         | [Named Actions](/reference/actions-processor/actions_named.md)                                  |

### Authentication Actions

These special actions allow you to create custom login and registration pages. See this page for more:

{% content-ref url="/pages/ndv0F4Y91eyJGYc9DphA" %}
[Authentication Actions](/reference/actions-processor/authentication-actions.md)
{% endcontent-ref %}

### Messaging Actions

| Action                   | Summary                                      | Details                                                                                           |
| ------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `messageSend`            | Sends a BetterForms message                  | [messageSend](/reference/actions-processor/actions_overview/messagesend.md)                       |
| `messageSendAnonChannel` | Sends a message to an anonymous channel flow | [messageSendAnonChannel](/reference/actions-processor/actions_overview/messagesendanonchannel.md) |
| `channelJoinAnon`        | Joins an anonymous channel                   | [channelJoinAnon](/reference/actions-processor/actions_overview/channeljoinanonymous.md)          |
| `channelLeaveAnon`       | Leaves an anonymous channel                  | [channelLeaveAnon](/reference/actions-processor/actions_overview/channelleaveanon.md)             |

### Payment Actions

| Action               | Summary                                                  | Details                                                                                   |
| -------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `showStripeCheckout` | Triggers the Stripe checkout event for a configured form | [showStripeCheckout](/reference/actions-processor/actions_overview/showstripecheckout.md) |

### OAuth Actions

| Action           | Summary                                    | Details                                                                                            |
| ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `authLoginOauth` | Finalizes OAuth login on the callback page | [authLoginOauth / oauthLoginHook](/reference/actions-processor/actions_overview/authloginoauth.md) |
| `oauthLoginHook` | Legacy alias for `authLoginOauth`          | [authLoginOauth / oauthLoginHook](/reference/actions-processor/actions_overview/authloginoauth.md) |

### PWA Actions

| Action                    | Summary                                                                      | Details                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `pwaCustomInstall`        | Captures the browser install prompt for later use                            | [pwaCustomInstall](/reference/actions-processor/actions_overview/pwacustominstall.md)               |
| `pwaPromptInstall`        | Triggers the stored browser install prompt                                   | [pwaPromptInstall](/reference/actions-processor/actions_overview/pwapromptinstall.md)               |
| `pwaPromptPushPermission` | Requests push-notification permission and registers the browser subscription | [pwaPromptPushPermission](/reference/actions-processor/actions_overview/pwapromptpushpermission.md) |
| `pwaPushNotificationSend` | Sends a push notification through BetterForms                                | [pwaPushNotificationSend](/reference/actions-processor/actions_overview/pwapushnotificationsend.md) |

### AI / Tooling Actions

| Action                | Summary                                                          | Details                                                                                     |
| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `llmToolCall`         | Maps LLM-requested frontend tools into BetterForms named actions | [llmToolCall](/reference/actions-processor/actions_overview/llmtoolcall.md)                 |
| `llmToolCallResponse` | Sends a frontend tool result back to the tool-response service   | [llmToolCallResponse](/reference/actions-processor/actions_overview/llmtoolcallresponse.md) |
| `llmQueryStop`        | Requests that an active `/llm/query` stream stop                 | [llmQueryStop](/reference/actions-processor/actions_overview/llmquerystop.md)               |
| `assistantStop`       | Requests that an active assistants run stop                      | [assistantStop](/reference/actions-processor/actions_overview/assistantstop.md)             |

## Usage

Actions can run from many places:

* `$$BF_Actions` payloads returned from supported FileMaker hooks
* navigation menu items
* page elements such as buttons
* named actions
* `*_actions` schema keys (where supported)

Wherever you see an `actions` key in BetterForms, it can be either:

* a single action object
* an array of action objects to run in sequence

### $$BF\_Actions - Actions Array

`$$BF_Actions` is the browser action array that applicable FileMaker hooks can return.

Each array element is one action object. BetterForms queues them and runs them in order.

For user-facing docs and custom scripts, clear queued actions with the public BetterForms helper:

```javascript
BF.actionsClear()
```

#### Stacking actions from FileMaker (Helper custom functions)

The Helper File’s **`BF_SetAction…` custom functions** (for example `BF_SetAction`, `BF_SetAction_Function`, `BF_SetAction_Path`, and action-specific helpers like `BF_SetAction_showAlert`) **append** one action object to the JSON array in `$$BF_Actions`. Each function reads the current `$$BF_Actions`, adds the next action at the end, and **returns the full updated array**.

**Pattern:** After each call, set `$$BF_Actions` to the **return value** of the custom function. The next call then appends to that result.

**Do not** use FileMaker’s `List()` (or similar) to merge multiple actions—those helpers already merge into the JSON array.

Your Helper may ship multiple versions of a function (for example a generator variant). Use the **names from your Helper file**; the examples below use the common names **without** a `_G` suffix.

Example script steps:

```filemaker
Set Variable [ $$BF_Actions ; Value: BF_SetAction_Function ( "model.ui.isLoading = true;" ) ]
Set Variable [ $$BF_Actions ; Value: BF_SetAction_Path ( "/orders" ) ]
Set Variable [ $$BF_Actions ; Value: BF_SetAction_Function ( "model.ui.isLoading = false;" ) ]
```

Generic action + options (second parameter is a JSON **string** for `options`, or `""` when empty):

```filemaker
Set Variable [ $$BF_Actions ; Value: BF_SetAction ( "runUtilityHook" ; "{ \"type\": \"save\" }" ) ]
```

For other globals built by FileMaker (`$$BF_Model`, `$$BF_App`, etc.), see [Global Variables for Hooks](/reference/hooksoverview/filemaker-globals.md). Only `$$BF_Actions` is an ordered action queue built this way.

### Other places you can use actions

`actionsBeforeComplete` can be added to `schema.form` and BetterForms will run that action array when present.

### The Action Object

|            Key |   Type  | Default | Description                                                                                                                                                                                                                                                                                |
| -------------: | :-----: | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|       `action` |  string |         | The name of the action                                                                                                                                                                                                                                                                     |
|     `function` |  string |         | {optional} All actions can also take a function. This is processed just before the action is executed. This function can be an JS code and can also easily change the action parameters itself of any other environmental value. This is handy for pre-processing data prior to an action. |
| `preventClone` | boolean | false   | {optional} When true, BetterForms does not strip object references before running the action array. By default, actions are cloned so they are decoupled from the original objects that created them.                                                                                      |
|  `nonBlocking` | boolean | false   | {optional} When added to the action and true, the actions processor will not wait for the action to complete before starting the next action. This is useful when you have a blocking action but still want other things to run (like slow process utility hooks)                          |
|      `options` |  object |         | This object may be optional depending on the specific settings needed by a given action.                                                                                                                                                                                                   |

## `function` On Any Action

Any action object can also include a `function` key. When present, BetterForms runs that JavaScript just before the action executes.

Use this for pre-processing or mutating the action/options just before the action runs.

This is different from the standalone [`function` action](/reference/actions-processor/actions_overview/function-1.md), which is itself the action being executed.

## Calling Named Actions <a href="#functions" id="functions"></a>

### Triggering Actions on Field Changes

All field element types support an `onChanged_actions` key. This key can contain actions that will be run when the elements data model changes.

```
// This will show an alert when the checkbox is toggled
{
  "styleClasses": "col-md-4",
  "text": "Enter Address Manually",
  "type": "bfcheckbox1",
  "model": "manualAddress",
  "onChanged_actions": [
    {
      "action": "showAlert",
      "options": {
        "text": "This is the alert message text",
        "title": "Hello World",
        "type": "information"
      }
    }
  ]
}
```

### Clearing Actions

```javascript
// in a function key
if (!model.isRegistered) {
  BF.actionsClear()
}
```


---

# 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.klai.studio/reference/actions-processor/actions_overview.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.