Skip to main content

SDK Client Reference

Complete reference for @zaflun/lumio-sdk — the client-side library used in editor.tsx, layer.tsx, and interactive.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<T = Record<string, unknown>>(): {
  config: T | null;
  setConfig: (patch: Partial<T>) => Promise<void>;
  loading: boolean;
};

setConfig performs a shallow merge — only provided keys are updated. Available in all surfaces.

useLumioEvent​

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

function useLumioEvent<T = unknown>(eventType: LumioEventType): LumioEvent<T> | null;

The hook reference changes every time a new event arrives. Use in a useEffect dependency array to respond to each event individually.

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 54 event types grouped by platform (Twitch, YouTube, Kick, Trovo, Spotify, StreamElements, and per-platform/catch-all chat events).

useLumioAction​

Call a server function defined in server/functions.ts.

function useLumioAction(actionName: string): {
  invoke: (args: Record<string, unknown>) => Promise<unknown>;
  loading: boolean;
  error: Error | null;
};

invoke is stable across renders (memoized). loading is true while the server call is in flight.

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 authenticated viewer's identity on the interactive page. Always null on layer and editor.

function useLumioIdentity(): LumioIdentity | null;

interface LumioIdentity {
  userId: string;
  userName: string;
  platform: "twitch" | "youtube" | "kick" | "trovo" | 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" | "interactive" }): 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 or interactive page.

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>