Embedding Controls

When embedding a Semaphor dashboard in your application, you can set control values programmatically, lock controls to prevent changes, or hide controls entirely. This lets you tailor the dashboard experience based on application context.

Setting Default Control Values

Use the defaultControlValues prop to pre-set control values when the dashboard loads. Values are keyed by control ID.

import { Dashboard } from 'semaphor';
 
function AnalyticsDashboard({ userRegion }) {
  return (
    <Dashboard
      authToken={token}
      defaultControlValues={{
        region: userRegion,
        time_grain: 'month',
        use_estimated: true,
      }}
    />
  );
}

Each value must match the expected type for its control:

Locking Controls

Set locked: true on a control definition to make it visible but read-only. Viewers can see the current value but cannot change it.

This is useful when your application sets a control value based on the logged-in user's context (like their region or department) and you want to show what value is active without allowing changes.

<Dashboard
  authToken={token}
  defaultControlValues={{
    region: 'West',
  }}
/>

In this example, the region control is defined with locked: true in the dashboard configuration. The viewer sees "Region: West" in the toolbar but cannot change it.

Hiding Controls

Set hidden: true on a control definition to use a control value without showing any UI. The control still affects queries, but viewers do not see it.

Combine hidden with defaultControlValues to pass values programmatically without any visible control widget:

<Dashboard
  authToken={token}
  defaultControlValues={{
    tenant_id: currentUser.tenantId,
  }}
/>

Here, tenant_id is a hidden control used in SQL queries to filter data by tenant. The viewer never sees it, and the value is set entirely by your application.

Controls in Scheduled Reports

When a dashboard has controls, scheduled report attachments capture a snapshot of the control values at configuration time.

Each attachment can specify different control values. For example, you can schedule the same dashboard to be sent as two attachments:

• Attachment 1: Region = East
• Attachment 2: Region = West

Each recipient receives a report reflecting the control values configured for their attachment, regardless of what the dashboard shows interactively.

Controls in Alerts

When you configure an alert on a card that uses controls, Semaphor captures a snapshot of the current control values. The alert evaluates its condition using those saved control values on every run, ensuring consistent behavior regardless of what the dashboard shows interactively.

If a card uses a "Region" control set to "West" when the alert is created, every alert evaluation queries data for the West region.

Controls in Exports

When exporting a dashboard or card to PDF or CSV, the current control values are preserved. The export reflects exactly what the viewer sees with their current control selections.

If a viewer selects "Region: West" and "Time Grain: Quarter" before exporting, the PDF or CSV contains the data for the West region at quarterly granularity.