Skip to main content

SDK Client Reference

Complete reference for @zaflun/lumio-sdk - the client-side library used in the editor.tsx and layer.tsx surfaces.

Import​

import { Lumio, Box, Text, useLumioEvent, useLumioConfig /* ... */ } from "@zaflun/lumio-sdk";

Hooks​

useLumioConfig​

Read and write the extension's configuration set by the editor panel.

function useLumioConfig(): [
  LumioConfig,
  (configOrUpdater: LumioConfig | ((prev: LumioConfig) => LumioConfig)) => void,
];

Destructure the tuple as [config, setConfig]. The values defined in config_schema are in config.settings; the other LumioConfig fields identify the installation and target. setConfig accepts a complete config object or a functional updater. Preserve existing fields when updating one setting:

setConfig((prev) => ({
  ...prev,
  settings: { ...(prev.settings ?? {}), fontSize: 16 },
}));

Available in all surfaces. See the useLumioConfig reference for the full config shape.

useLumioEvent​

Subscribe to a live stream event. Returns the latest event of the given type, or null before the first event.

function useLumioEvent<K extends LumioEventType>(eventType: K): LumioEventPayloadMap[K] | null;

The hook returns the latest raw payload. Use useLumioEventListener when you need every event in arrival order; several events before a render can overwrite this hook's state.

The eventType parameter is typed as LumioEventType - editors with TypeScript support provide autocomplete over all supported values. See the useLumioEvent reference for the full list of event types grouped by platform (Twitch, YouTube, Kick, Spotify, StreamElements, and per-platform/catch-all chat events).

Test payloads include server-set isTest: true and showOnStream. Use isTestEvent(payload) from @zaflun/lumio-sdk to label them TEST in custom widgets. The helper also accepts an event row with raw or a notification with data, and returns true only for Boolean isTest or is_test markers. It is available from the package root and /server. Dashboard previews receive tests by default; OBS sources receive them only with showOnStream: true.

useLumioAction​

Run a Lumio action (for example events:emit) on behalf of your install. The host forwards it to the Lumio API, which checks the permission your manifest declares. See the useLumioAction reference for the supported actions, the surfaces that can run them and the error codes.

function useLumioAction(action: LumioActionType): {
  execute: (params?: Record<string, unknown>) => Promise<void>;
  data: unknown | null;
  isLoading: boolean;
  error: string | null;
};

execute is stable across renders as long as action does not change. For your own server functions in server/functions.ts use useQuery / useMutation.

useExtensionStorage​

Read and write key-based storage from the client side. Returns a tuple with the current value and a setter.

function useExtensionStorage<T = Record<string, unknown>>(
  key: string,
  initialValue: T,
): [T, (value: T) => void];

On mount, the hook requests the current value from the host. External updates (from other instances or the host) are received automatically. Client-side storage access requires "storage:read" (and "storage:write" to write) in permissions.

useLumioTheme​

Returns the streamer's active overlay theme.

function useLumioTheme(): LumioTheme;

interface LumioTheme {
  mode: "light" | "dark";
  primaryColor: string;        // hex color
  fontFamily: string;
  borderRadius: number;        // px
}

useLumioIdentity​

Returns the identity of the logged-in dashboard user on the editor surface. No surface carries a viewer identity: Lumio has no viewer page (see Viewer Input).

function useLumioIdentity(): LumioIdentity | null;

interface LumioIdentity {
  userId: string;
  userName: string;
  platform: "twitch" | "youtube" | "kick" | null;
  platformUserId: string | null;
  isAuthenticated: boolean;
}

useQuery​

Declarative query hook - calls a server query() function and returns the result.

function useQuery<T>(
  queryName: string,
  args: Record<string, unknown>,
  options?: { refetchInterval?: number }
): {
  data: T | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
};

refetchInterval polls on an interval (milliseconds). Use useLumioAction instead if you need imperative control.

useMutation​

Imperative mutation hook - wraps a server action() call with loading and error state.

function useMutation<TArgs, TResult>(
  actionName: string
): {
  mutate: (args: TArgs) => Promise<TResult>;
  loading: boolean;
  error: Error | null;
  reset: () => void;
};

Components​

Lumio.render​

Entry point for mounting a surface.

Lumio.render(element: React.ReactElement, options: { target: "layer" | "editor" }): void;

Must be called exactly once per surface file.

Box​

A general-purpose layout container. Renders a <div>.

interface BoxProps {
  style?: React.CSSProperties;
  children?: React.ReactNode;
  onClick?: () => void;
  ref?: React.Ref<HTMLDivElement>;
  [key: string]: unknown; // data-* attributes passed through
}

Text​

Renders inline text with semantic variants.

interface TextProps {
  content: string;
  variant?: "default" | "heading" | "muted" | "label" | "code";
  style?: React.CSSProperties;
}

Image​

Renders an image with automatic HTTPS enforcement and lazy loading.

interface ImageProps {
  src: string;
  alt: string;
  style?: React.CSSProperties;
  onError?: () => void;
}

Input​

A text input field for use in the editor panel.

interface InputProps {
  label?: string;
  value: string;
  onChange: (value: string) => void;
  placeholder?: string;
  type?: "text" | "email" | "url" | "password" | "number";
  disabled?: boolean;
}

Select​

A dropdown select field for use in the editor panel.

interface SelectProps {
  label?: string;
  value: string;
  options: Array<{ value: string; label: string }>;
  onChange: (value: string) => void;
  disabled?: boolean;
}

Toggle​

A boolean toggle switch for use in the editor panel.

interface ToggleProps {
  label: string;
  checked: boolean;
  onChange: (checked: boolean) => void;
  disabled?: boolean;
}

Button​

An interactive button for use in the editor panel.

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: "primary" | "secondary" | "danger";
  loading?: boolean;
  disabled?: boolean;
  style?: React.CSSProperties;
}

Animation utilities​

defineKeyframes​

Registers a CSS keyframe animation and returns a unique name safe for use in animation: CSS properties.

function defineKeyframes(frames: Record<string, React.CSSProperties>): string;
const slideIn = defineKeyframes({
  from: { opacity: 0, transform: "translateY(-20px)" },
  to: { opacity: 1, transform: "translateY(0)" },
});

// Use in a Box style:
style={{ animation: `${slideIn} 0.4s ease forwards` }}

localFont​

Loads a font file bundled with the extension and returns a CSS font-family value.

function localFont(options: { src: string; weight?: string; style?: string }): string;
const myFont = localFont({ src: "./assets/CustomFont.woff2", weight: "400 700" });

<Box style={{ fontFamily: myFont }}>...</Box>