useProperties

Subscribes to custom property values defined in the wallpaper manifest (fluxlay.yaml) and customized by the end user through the Fluxlay app settings UI.

Import

import { useProperties } from "@fluxlay/react";

Signature

function useProperties<T extends PropertyValues = PropertyValues>(): T;

Type Parameters

Parameter	Default	Description
`T`	`PropertyValues`	Shape of the property values object. Extends `Record<string, number \| string \| boolean \| string[] \| null>`.

Return Value

Returns an object containing the current property values. Each key corresponds to a property ID defined in fluxlay.yaml. The values reflect the defaults from the manifest, overridden by any user customizations.

Returns {} until the initial values are fetched.

Manifest Definition

Properties are defined in fluxlay.yaml:

fluxlay.yaml

schemaVersion: 1
properties:
  particleCount:
    type: number
    label: Particle Count
    default: 100
    min: 10
    max: 500
    step: 10
  themeColor:
    type: color
    label: Theme Color
    default: "#ff6b35"
  showClock:
    type: boolean
    label: Show Clock
    default: true
  animationStyle:
    type: select
    label: Animation Style
    default: wave
    options:
      - value: wave
        label: Wave
      - value: spiral
        label: Spiral

See the Manifest Reference for the full properties schema.

Property Types

Type	TypeScript Type	UI Control	Description
`number`	`number`	Stepper / Number input	Numeric value with optional min/max/step.
`range`	`number`	Slider	Numeric value rendered as a slider. `min` and `max` are required.
`color`	`string`	Color Picker	Hex color string (e.g. `"#ff6b35"`).
`boolean`	`boolean`	Toggle Switch	True or false.
`text`	`string`	Text input	Free-form text. Optional `maxLength` and `placeholder`.
`select`	`string`	Dropdown	Single-select from predefined options.
`multi-select`	`string[]`	Checklist / Multi-select	Multi-select from predefined options. Optional `min` / `max` count constraints.
`image`	`string \| null`	File picker (images)	Absolute path of a user-picked local image, or `null` if not set.
`file`	`string \| null`	File picker	Absolute path of a user-picked local file, or `null` if not set.
`font`	`string`	Font selector	Font family name. Use `sources: [system, google]` to control where fonts are pulled from.

Example

interface WallpaperProperties {
  particleCount: number;
  themeColor: string;
  showClock: boolean;
  animationStyle: string;
}
 
function Wallpaper() {
  const { particleCount, themeColor, showClock, animationStyle } = useProperties<WallpaperProperties>();
 
  return (
    <div style={{ backgroundColor: themeColor }}>
      <p>Particles: {particleCount}</p>
      <p>Animation: {animationStyle}</p>
      {showClock && <Clock />}
    </div>
  );
}

Notes

Property values are fetched on mount and then streamed in real time. When the user changes a value in the settings UI, the hook re-renders with the updated value immediately.
User customizations are persisted per wallpaper slug. Reinstalling or re-assigning the same wallpaper restores the previous customizations.
This hook only works inside the Fluxlay desktop app. In a normal browser, it returns {}.
image / file values are host OS file paths. Implement a fallback in your wallpaper, since the file may move or be deleted after selection.
The manifest must declare schemaVersion: 1. The legacy type: string is removed and split into select (with options) and text (free-form input).