SmartSuite Script widgets can subscribe to dashboard events and react to Filter widget state changes almost immediately. This enables truly interactive dashboards where scripts respond automatically to user-driven context changes instead of operating in isolation.

This article explains what’s supported in V1, how subscriptions work, and how to implement them safely and correctly.

Plan Availability	Professional, Enterprise and Signature (the Scripting Widget is available on the Professional plan or higher)
Permissions	Solution Managers and Administrators: add and configure Script widgets on the dashboards of the Solutions they manage.
Platform	Web
Related Reading	Scripting widget Filter widget Advanced Scripting Functions Secrets Management.

My script does not react to the filter: check these five things, in order

Solution Managers and Administrators configure Script widgets. If you cannot edit the dashboard, send this page and the dashboard name to the person who manages the solution.

No explicit subscription. Subscribe to the Filter widget by its id; there is no dashboard-wide subscription. See Recommended Approach: Subscription API.
An unsupported event. Grid selection, record focus, page navigation and cross-solution events do not trigger scripts. See Not supported.
Data changed, not the filter. Only a change to the filter configuration fires an event; new records matching the filter do not. See Important Behavioral Notes.
No state on load. Set emitInitial to true to receive the current filter state when the script loads. See Key Concepts.
The Filter widget is gone. A deleted or unavailable widget fails gracefully and the dashboard keeps working. See Execution Behavior and Guarantees.

Still stuck: select the chat button in the lower-right corner of SmartSuite. The last block of the panel shows the service status, and Send a message in the same panel reaches support. Include the dashboard name, the widget ids and the console output. The widget itself is described in Scripting widget.

What This Feature Enables

Previously, Script widgets could not observe or access the state of other widgets. With this release:

Script widgets can subscribe to specific Filter widgets
Scripts automatically execute when a subscribed Filter widget changes value
Scripts also execute once on load, receiving the current filter state even if no change has occurred
All execution is event-driven, without manual script runs
Subscriptions are resilient to reloads and isolated from dashboard failures

This allows dashboards to behave like cohesive applications, not static collections of widgets.

Scope and Limitations (V1)

Supported

Subscribing to Filter widget value changes
Subscribing to multiple Filter widgets
Subscribing to Filter widgets on other dashboards within the same solution
Automatic execution on:
- Filter value change
- Initial load with current filter state
Graceful handling of widget reloads or failures

Not supported

Grid selection events
Record focus changes
Page navigation events
Cross-solution subscriptions
Background or scheduled execution
Persistence of filter values beyond the dashboard lifecycle
Guaranteed stability of event payload shape

Existing Script widgets without subscriptions continue to work exactly as before.

Event Model Overview

Script widgets run inside a sandboxed iframe and communicate through the window.SmartSuite API.

There are two supported interaction patterns:

Global event listeners
Explicit widget subscriptions (recommended)

Subscriptions are widget-scoped, not dashboard-wide. Only events from explicitly subscribed Filter widgets will trigger execution.

Recommended Approach: Subscription API

Basic Subscription Example

<body>
  <p id="output"></p>
<script>
    const FILTER_WIDGET_ID = "filter-widget-id";
window.SmartSuite.subscribe({
      source: {
        widgetId: FILTER_WIDGET_ID,
        widgetType: "filter",
      },
      events: ["filter.changed"],
      options: {
        emitInitial: true,
        debounceMs: 150,
      },
      onEvent: (evt) => {
        console.log("Filter event received:", evt.payload);
const output = document.getElementById("output");
        output.innerText =
          evt.payload.filter.conditions[0]?.value ?? "No value";
      },
    }).then((sub) => {
      console.log("Subscribed with ID:", sub.subscriptionId);
    });
  </script>
</body>

Key Concepts

emitInitial: true ensures your script receives the current filter state on load
debounceMs prevents rapid successive filter changes from triggering excessive executions
onEvent runs automatically whenever the subscribed Filter widget changes

Subscribing to Multiple Filter Widgets

A Script widget may subscribe to multiple Filter widgets. Any change in any subscribed widget triggers execution.

Each subscription is explicit and independent. There is no implicit dashboard-wide subscription behavior.

Global Event Listener (Alternative)

You may also listen globally and manually filter events:

const off = window.SmartSuite.on("filter.changed", (evt) => {
  if (evt.source.widgetId !== FILTER_WIDGET_ID) return;
  console.log("filter.changed", evt.payload);
});

This approach is less targeted and is generally discouraged unless you have advanced routing needs.

Accessing Current Filter State On Demand

You can fetch the current state of a Filter widget without subscribing:

window.SmartSuite.getState({
  source: { widgetId: FILTER_WIDGET_ID },
  stateType: "filter.selections",
}).then((state) => {
  console.log("Current filter state:", state);
});

This is useful for initialization logic or validation, but it does not replace subscriptions for reactive behavior.

Execution Behavior and Guarantees

Scripts execute:
- Once on load with the current filter state
- Every time a subscribed Filter widget changes
If a Script widget iframe reloads, subscriptions are automatically re-established
If a subscribed Filter widget is deleted or unavailable:
- The script fails gracefully
- The dashboard continues functioning normally
Script errors are isolated and cannot break the dashboard

Important Behavioral Notes

Only filter configuration changes trigger events
Example: changing a filter from “In Progress” to “Completed”
Data updates that match an existing filter (for example, a new record entering the filter via sockets) do not trigger script execution

Best Practices

Always subscribe explicitly to the widgets you depend on
Use emitInitial to avoid undefined state on load
Add defensive checks for missing payload fields
Keep scripts idempotent and fast, as they may execute frequently
Assume event payload shapes may evolve in future versions

This V1 release establishes the foundation for event-driven, interactive dashboards in SmartSuite.

Last verified 29 Oct 2026.

Subscribing Script Widgets to Filter Widget State Changes