useLumioConfig

Read and write the extension's user-configurable settings as defined in config_schema in lumio.config.json. Config values are persisted per installation and displayed in a dedicated settings UI separate from the main editor panel.

Signature

const [config, setConfig] = useLumioConfig<T>();

Parameters

This hook takes no parameters.

Return value

Returns a tuple of two values:

Index	Type	Description
0	T	Current config object (typed by your config_schema)
1	(config: T | (prev: T) => T) => void	Setter function -- accepts a new config object or a functional updater

Example

Define the schema in lumio.config.json:

{
  "config_schema": {
    "primaryColor": {
      "type": "string",
      "label": "Primary color",
      "default": "#6366f1"
    },
    "showAvatar": {
      "type": "boolean",
      "label": "Show avatar",
      "default": true
    },
    "fontSize": {
      "type": "number",
      "label": "Font size (px)",
      "default": 16
    }
  }
}

Then use it in any surface:

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

interface MyConfig {
  primaryColor: string;
  showAvatar: boolean;
  fontSize: number;
}

function AlertOverlay() {
  const [config] = useLumioConfig<MyConfig>();

  return (
    <Box
      style={{
        background: config.primaryColor,
        fontSize: config.fontSize,
      }}
    >
      <Text content="New follower!" variant="heading" />
    </Box>
  );
}

Functional updater

The setter accepts a functional updater (prev) => next, which is the recommended pattern in editor.tsx to avoid overwriting concurrent changes:

import { useLumioConfig, EditorInput, EditorSlider } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();

  // Functional updater -- recommended for editor.tsx
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({
      ...prev,
      settings: { ...(prev.settings ?? {}), [key]: value },
    }));

  return (
    <>
      <EditorInput
        label="Title"
        value={String(config.settings?.title ?? "")}
        onChange={(v) => update("title", v)}
      />
      <EditorSlider
        label="Opacity"
        value={Number(config.settings?.opacity ?? 100)}
        onChange={(v) => update("opacity", v)}
        min={0}
        max={100}
        unit="%"
      />
    </>
  );
}

The functional form (prev) => next is safer than passing a full object because it reads the latest state at update time, preventing race conditions when multiple fields update in quick succession.

Difference from useExtensionStorage

	useLumioConfig	useExtensionStorage
Schema	Defined in config_schema (typed)	Untyped key-value
UI	Auto-generated settings panel	Custom editor panel in src/editor.tsx
Purpose	User-facing settings (theme, preferences)	Runtime state (scores, current topic)
Scope	Per installation	Per installation

Notes

• The config values are initialized with defaults from config_schema on first install
• Changes to config trigger a re-render on all surfaces that use useLumioConfig()
• Config is not intended for high-frequency updates (use useExtensionStorage() for that)
• Type parameter T is optional but strongly recommended for type safety
• 17 field types are supported in config_schema: string, number, boolean, color, select, textarea, slider, font, icon, image, sound, multiselect, group, divider, info, channel, designer — see lumio.config.json reference for details