useWidgetContext

Hook for accessing widget context information, including widgetId, dashboardId, layout and dashboard filters. Context data loads asynchronously, so the output is undefined while loading.

For module configuration and setup instructions, see Dashboard widget.

Installation

Install Forge hooks using the @forge/hooks npm package. Import @forge/hooks using a bundler, such as Webpack.

Usage

To add the useWidgetContext hook to your app:

1
2
import { useWidgetContext } from "@forge/hooks/dashboards";

Here is an example of accessing widget context information:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import React from "react";
import { useWidgetContext } from "@forge/hooks/dashboards";

const getFilterLabels = (expression) => {
  if (!expression) {
    return [];
  }

  if ("groups" in expression) {
    return expression.groups.flatMap(getFilterLabels);
  }

  return expression.label ? [expression.label] : [];
};

function MyWidget() {
  const context = useWidgetContext();

  if (!context) return <div>Loading...</div>;

  const { layout, widgetId, dashboardId, filters } = context;
  const filterLabels = getFilterLabels(filters);

  return (
    <div style={{ width: layout.width, height: layout.height }}>
      <p>Widget ID: {widgetId}</p>
      <p>Dashboard ID: {dashboardId}</p>
      <p>
        Size: {layout.width}x{layout.height}
      </p>
      <p>Dashboard filters: {filterLabels.join(", ") || "None"}</p>
    </div>
  );
}

Function signature

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
function useWidgetContext(): UseWidgetContextType | undefined;

interface UseWidgetContextType {
  layout: Layout;
  widgetId?: string;
  dashboardId: string;
  filters: FilterExpression | null;
}

interface Layout {
  /**
   * The width of the container of the widget in px.
   */
  width: number;
  /**
   * The height of the container of the widget in px.
   */
  height: number;
  /**
   * The row span of the widget.
   */
  rowSpan?: "xsmall" | "small" | "medium" | "large";
  /**
   * The column span of the widget in a 12 column grid.
   */
  columnSpan?: 3 | 4 | 6 | 8 | 12;
}

Returns

• UseWidgetContextType: Widget context object containing:
  • layout (Layout): Widget dimensions and grid positioning
  • widgetId (string | undefined): Unique widget identifier, undefined if it's a new widget
  • dashboardId (string): Parent dashboard identifier
  • filters (FilterExpression | null): Dashboard filters available to the widget. Returns null when there is no active filter expression.

Dashboard filters

Dashboard widgets can receive dashboard filters through the filters property. This is typed as a FilterExpression tree. Typically on the dashboard, FilterExpressions are nested as a root dashboard-level FilterGroup containing product-specific FilterGroups, which themselves contain individual leaf node Filters.

Apps can define custom dashboard filters using the Dashboard filter (EAP) module.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
type FilterExpression = FilterGroup | Filter;

interface FilterGroup {
  id: string;
  operator: "AND" | "OR";
  groups: FilterExpression[];
}

type Filter = AvpStoredFilter | AppStoredFilter;

interface AvpStoredFilter {
  id: string;
  label: string;
  comparison: string;
  defaultValues: Array<string | null>;
  metadata?: string;
  dimensions: FilterDimension[];
}

interface AppStoredFilter {
  id: string;
  label: string;
}

interface FilterDimension {
  name: string;
  product?: string;
  subProduct?: string | null;
  dynamicDimensionKey?: string; // The key for any custom field dimensions
}