# 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

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

## Signature

```tsx
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`:

```yaml title="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](/en/studio/developer/reference/cli/manifest.md) 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

```tsx
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).