Filters

A filter is the filter key in a component's state. It changes what a viewer is looking at; it does not grant access to rows outside the embed's partition.

Different components accept different filter shapes: a menu may take a scalar, a range may take [lo, hi], and a chart brush may take nested ranges. Read the state schema instead of guessing.

Read filters

Iframe

const state = await getState(); // request ridge:getState; see Dashboard state
const filters = Object.fromEntries(
  Object.entries(state)
    .filter(([, values]) => "filter" in values)
    .map(([id, values]) => [id, values.filter])
);

Inline

await ridge.ready;
const filters = ridge.getFilters();
// { "region-menu": "EMEA", "date-range": ["2026-01-01", "2026-06-30"] }

Components with no active filter are absent from the result.

Set filters

Iframe

frame.contentWindow.postMessage(
  {
    type: "ridge:setState",
    state: { "region-menu": { filter: "APAC" } }
  },
  ridgeOrigin
);

Inline

const result = await ridge.setFilters({ "region-menu": "APAC" });
result.filters; // every active filter after the write
result.changed; // component ids that changed
result.errors; // rejected writes

Write null to clear a filter. The iframe expresses filters through the shared state protocol; the inline API provides flatter convenience methods over that same state key.

React to filter changes

Iframe

window.addEventListener("message", (event) => {
  if (event.source !== frame.contentWindow || event.origin !== ridgeOrigin) return;
  if (event.data?.type !== "ridge:stateChange") return;

  const filter = event.data.state["region-menu"]?.filter;
  syncRegionControl(filter);
});

Inline

ridge.on("filterchange", ({ filters, changes, source }) => {
  if (source === "user") syncMyControls(filters, changes);
});

The inline event distinguishes "user" from "api" changes. The iframe protocol sends the resulting state; use a silent write when the host should not receive an echo.

Validate a value

Iframe

// Read `stateSchema` from ridge:ready or request ridge:getStateSchema.
const filterSchema = stateSchema["region-menu"]?.filter?.schema;

Inline

const filterSchema = ridge.getStateSchema()["region-menu"]?.filter?.schema;

The returned value is a JSON Schema draft 2020-12 fragment. Validate against it directly; do not infer a filter's shape from its component type or id.