# React · useLight

Creates and configures a light handle.

Package: @bolerish/edge 0.4.0
Source: https://edge.bolerish.com/docs/react/use-light/

<a id="use-light"></a>

## useLight(options?)

Returns a stable `Light` handle for explicit ownership without a provider. Pass it to `useSurface(light, options)`. Option changes update the existing light; use `Edge.Provider` for ordinary component trees.

```tsx
function useLight(options?: LightOptions): Light;
```

| Prop / option | Type | Default | Description |
| --- | --- | --- | --- |
| `motion` | `'system' \| 'dynamic' \| 'static'` | `'system'` | System respects reduced-motion and device preferences. Dynamic follows mouse or pen input, even with reduced motion enabled. Static keeps a fixed direction. Touch updates the light position in viewport coordinates. Scrolling and lifting the finger preserve the last position; surfaces respond as they move beneath it. A new touch updates the position. Touch tracking follows the selected motion mode: static stays fixed, and system stays fixed when reduced motion is enabled. |
| `staticDirection` | `number \| 'random'` | `315` | Direction in degrees for fixed lighting. Random chooses one shared direction per mount and keeps it across ordinary rerenders. Numbers must be finite. |
| `direction` | `'toward' \| 'away'` | `'toward'` | toward faces highlights toward the pointer; away reverses them by 180 degrees. All surface styles preserve this choice. Only affects pointer-driven lighting; staticDirection controls fixed lighting. |
| `range` | `number` | `480` | Distance over which dynamic lighting fades outside a surface, in viewport CSS pixels. Must be positive and finite. |
| `intensity` | `number` | `0.75` | Shared light strength. Must be finite and between 0 and 1; invalid values throw a RangeError. |

`range` affects dynamic lighting only. Fixed lighting uses `staticDirection` without distance attenuation.

<a id="refresh"></a>

## light.refresh()

Remeasures surfaces on the next frame, even with a stationary pointer. Call after React commits changes to an element’s position or border thickness without a size notification.

```tsx
interface Light {
  refresh(): void;
}
```

Size changes and scrolling are handled automatically; see [layout updates](https://edge.bolerish.com/docs/integration/#refresh-after-layout-changes) for details.