Settings & Property Inspector

Settings Sync Architecture

┌──────────────┐       setSettings()        ┌──────────────────┐
│  React Tree  │ ────────────────────────>   │  Stream Deck SDK │
│  (useState)  │                             │  (persisted)     │
│              │ <────────────────────────   │                  │
└──────────────┘   onDidReceiveSettings      └──────────────────┘
                                                      ↕
                                             ┌──────────────────┐
                                             │ Property Inspector│
                                             │ (HTML/JS UI)     │
                                             └──────────────────┘

React to SDK: calling setSettings({ count: 5 }) updates the React state (triggers re-render) and calls action.setSettings() to persist.
SDK to React: when the Property Inspector changes settings, onDidReceiveSettings fires and the React state updates.
Conflict resolution: the SDK is the source of truth (last-write-wins).

Per-Action Settings

type MySettings = { color: string; brightness: number };

function MyKey() {
  const [settings, setSettings] = useSettings<MySettings>();

  useKeyDown(() => {
    setSettings({ brightness: Math.min(100, settings.brightness + 10) });
  });

  // settings.color, settings.brightness are reactive
}

setSettings uses shallow merge ({ ...current, ...partial }), matching the SDK behavior.

Global Settings

type GlobalConfig = { apiKey: string; theme: 'light' | 'dark' };

function MyKey() {
  const [global, setGlobal] = useGlobalSettings<GlobalConfig>();
  // Shared across all action instances
}

Property Inspector Communication

Beyond settings, you can send arbitrary messages between the plugin and the Property Inspector:

Sending to PI

function MyKey() {
  const sendToPI = useSendToPI();

  useKeyDown(() => {
    sendToPI({ currentState: 'active', timestamp: Date.now() });
  });
}

Receiving from PI

function MyKey() {
  usePropertyInspector<{ action: string }>((msg) => {
    if (msg.action === 'refresh') {
      // Handle PI message
    }
  });
}

Default Settings

Set default values in defineAction so new instances start with sensible state:

export const myAction = defineAction<MySettings>({
  uuid: 'com.example.plugin.my-action',
  key: MyKey,
  defaultSettings: { color: '#000', brightness: 50 },
});