Event Hooks

React hooks for Stream Deck hardware events -- key presses, dial rotation, touch taps, and dial hints.

Event hooks subscribe to Stream Deck hardware events and fire callbacks inside the React tree.

useKeyDown

Fires when a key is pressed down.

function useKeyDown(callback: (payload: KeyDownPayload) => void): void;

interface KeyDownPayload {
  settings: JsonObject;
  isInMultiAction: boolean;
  state?: number;
  userDesiredState?: number;
}

function CounterKey() {
  const [count, setCount] = useState(0);

  useKeyDown(() => {
    setCount((c) => c + 1);
  });

  return (
    <div style={{ width: '100%', height: '100%', alignItems: 'center', justifyContent: 'center', background: '#000' }}>
      <span style={{ color: 'white', fontSize: 32 }}>{count}</span>
    </div>
  );
}

useKeyUp

Fires when a key is released.

function useKeyUp(callback: (payload: KeyUpPayload) => void): void;

interface KeyUpPayload {
  settings: JsonObject;
  isInMultiAction: boolean;
  state?: number;
  userDesiredState?: number;
}

function HoldKey() {
  const [pressed, setPressed] = useState(false);

  useKeyDown(() => setPressed(true));
  useKeyUp(() => setPressed(false));

  return (
    <div style={{
      width: '100%', height: '100%',
      alignItems: 'center', justifyContent: 'center',
      background: pressed ? '#4CAF50' : '#333',
    }}>
      <span style={{ color: 'white', fontSize: 18 }}>
        {pressed ? 'HELD' : 'PRESS'}
      </span>
    </div>
  );
}

useDialRotate

Fires when a dial/encoder is rotated.

function useDialRotate(callback: (payload: DialRotatePayload) => void): void;

interface DialRotatePayload {
  ticks: number;     // Positive = clockwise, negative = counter-clockwise
  pressed: boolean;  // Whether the dial is pressed while rotating
  settings: JsonObject;
}

function VolumeDial() {
  const [volume, setVolume] = useState(50);

  useDialRotate(({ ticks }) => {
    setVolume((v) => Math.max(0, Math.min(100, v + ticks)));
  });

  return (
    <div style={{ width: '100%', height: '100%', alignItems: 'center', justifyContent: 'center', background: '#1a1a1a' }}>
      <span style={{ color: 'white', fontSize: 28 }}>{volume}%</span>
    </div>
  );
}

useDialDown / useDialUp

Fire when a dial is pressed / released.

function useDialDown(callback: (payload: DialPressPayload) => void): void;
function useDialUp(callback: (payload: DialPressPayload) => void): void;

interface DialPressPayload {
  settings: JsonObject;
  controller: 'Encoder';
}

useTouchTap

Fires when the touch strip area is tapped.

function useTouchTap(callback: (payload: TouchTapPayload) => void): void;

interface TouchTapPayload {
  tapPos: [x: number, y: number];  // Coordinates of the tap
  hold: boolean;                    // Whether it was a long press
  settings: JsonObject;
}

useDialHint

Sets the trigger descriptions shown on Stream Deck+ for what the dial actions do. Updates automatically when hints change.

function useDialHint(hints: DialHints): void;

interface DialHints {
  rotate?: string;
  press?: string;
  touch?: string;
  longTouch?: string;
}

function VolumeDial() {
  const [muted, setMuted] = useState(false);

  useDialHint({
    rotate: 'Adjust volume',
    press: muted ? 'Unmute' : 'Mute',
  });

  // ...
}

Under the hood, useDialHint calls action.setTriggerDescription() whenever the hint values change.

Implementation Pattern

All event hooks follow the same internal pattern: they subscribe to the root's EventBus via useEffect and use a stable callback ref to avoid stale closures without causing re-subscriptions.