useSettings

useSettings() exposes the active theme’s customizable schema plus the current overrides, with set / reset operations. The Settings system window uses it; consumers building their own settings UI use the same surface.

Import

import { useSettings } from "@react-ui-os/desktop";

Returns

Property	Type	Description
schema	Record<string, CustomizableField>	The active theme’s customizable map. Empty {} when the theme exposes none.
prefs	Record<string, unknown>	Current user overrides keyed by the same dotted paths. {} when nothing has been set.
setPref	(path: string, value: unknown) => void	Write a single override. Triggers immediate re-render of the desktop.
resetPref	(path: string) => void	Remove one override, falling back to the theme default.
resetAll	() => void	Clear every override for the active theme.

Examples

A custom accent picker outside Settings

function AccentChip({ hex }: { hex: string }) {
  const { setPref } = useSettings();
  return (
    <button
      onClick={() => setPref("palette.accent", hex)}
      style={{ background: hex }}
    />
  );
}

Conditional UI based on the schema

const { schema } = useSettings();
const supportsLeftDock = "chrome.dockPosition" in schema;

Reset to defaults from a menu item

function ResetMenu() {
  const { resetAll, prefs } = useSettings();
  const hasOverrides = Object.keys(prefs).length > 0;
  return hasOverrides ? <button onClick={resetAll}>Reset all settings</button> : null;
}

Persistence

setPref writes synchronously through the active StorageAdapter under the key settings:<themeId>. The change event fires, the desktop context re-reads, the effective theme rebuilds, every useTheme() consumer re-renders. No polling.

See also

• Settings: the default UI built on this hook.
• Customizable schema: what shapes schema can take.
• StorageAdapter: where prefs persist.