# React · useSurface

Returns a ref that connects an existing DOM element to a light.

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

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

## useSurface(options?)

Returns a callback ref that connects an existing HTML element to the nearest provider. Attach it to the element displaying the border and keep your existing `className` and `style`.

```tsx
const ref = useSurface<HTMLElement>(options);
```

```tsx
function Area() {
  return <Edge.Provider><ExistingCard /><ExistingCard /></Edge.Provider>;
}

function ExistingCard() {
  const ref = useSurface<HTMLDivElement>();
  return <Card ref={ref}>Your existing component</Card>;
}
```

In React 18, an existing function component must use `forwardRef` to pass the ref to its HTML element. React 19 also supports receiving ref as a prop.

Without an explicit light, this hook requires an Edge.Provider. For advanced ownership, use `useSurface(light, options)` with a handle returned by `useLight`. The explicit light takes precedence over the provider.

| Prop / option | Type | Default | Description |
| --- | --- | --- | --- |
| `pseudoElement` | `'after' \| 'before'` | `'after'` | Decoration slot. Choose before to preserve an existing ::after. If both slots are occupied, or the element is a native input, use a wrapper. Invalid values throw a RangeError. |
| `edgeStyle` | `'raised' \| 'recessed' \| 'matte'` | `'raised'` | How the edge responds to light. All three styles preserve your component appearance. |
| `color` | `string` | `currentColor` | Highlight color. Follows the element's text color by default. Accepts any CSS color string, including a CSS variable. |
| `shadowColor` | `string` | `#0008` | Color on the opposite edge. Accepts any CSS color string; use transparent to remove this shadow on a light surface. |
| `borderWidth` | `number` | `1` | Decorative edge thickness in pixels; it does not change the element's border. Negative values clamp to 0. Non-finite values use the default. |
| `intensity` | `number` | `1` | Multiplier for the shared light strength. Finite values clamp to 0–1; non-finite values use the default. |

A DOM element can connect to only one light. Do not attach the ref to a parent element with different dimensions.

Options update without replacing the element. Hook decoration attaches after hydration; use `Edge.Surface` to include appearance classes and variables in server output.