Subscribing Script Widgets to Filter Widget State Changes

SmartSuite Script widgets can now subscribe to dashboard events and react to Filter widget state changes in near real time. 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.

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 (Yet)

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
This distinction is intentional and aligns with future roadmap items like record-focused events

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

What’s Next

Future releases may add support for:

Grid selection changes
Record focus events
Page navigation events
Developer diagnostics and event inspection tools

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

Dashboards: Filter Widget