# React · useSurface

Devuelve una ref que conecta un elemento DOM existente a una luz.

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

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

## useSurface(options?)

Devuelve un ref de callback que conecta un elemento HTML existente al Edge.Provider más cercano. Asígnalo al elemento que muestra el borde. Puedes conservar sus propiedades `className` y `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>;
}
```

En React 18, los componentes de función deben usar `forwardRef` para pasar el ref al elemento HTML. React 19 también permite recibir ref como prop.

Si no pasas una luz explícita, necesitas Edge.Provider. Para gestionar la luz directamente, pasa el objeto devuelto por `useLight` a `useSurface(light, options)`. La luz explícita tiene prioridad sobre la de Edge.Provider.

| Prop / opción | Tipo | Predeterminado | Descripción |
| --- | --- | --- | --- |
| `pseudoElement` | `'after' \| 'before'` | `'after'` | Pseudoelemento de decoración. Elige before para conservar un ::after existente. Si ambos están ocupados o el elemento es una entrada nativa, usa un contenedor. Los valores inválidos lanzan RangeError. |
| `edgeStyle` | `'raised' \| 'recessed' \| 'matte'` | `'raised'` | Cómo responde el borde a la luz. Los tres estilos conservan la apariencia del componente. |
| `color` | `string` | `currentColor` | Color del reflejo. Usa el color de texto del elemento por defecto. Acepta cualquier cadena de color CSS, incluidas variables. |
| `shadowColor` | `string` | `#0008` | Color del borde opuesto. Acepta cualquier color CSS; usa transparent para quitar esta sombra en superficies claras. |
| `borderWidth` | `number` | `1` | Grosor decorativo en píxeles; no cambia el borde del elemento. Los negativos se limitan a 0. Los valores no finitos usan el predeterminado. |
| `intensity` | `number` | `1` | Multiplicador de la intensidad compartida. Los valores finitos se limitan a 0–1; los no finitos usan el predeterminado. |

Un elemento DOM solo puede conectarse a una luz. No asignes el ref a un elemento padre con dimensiones distintas.

Las opciones se actualizan sin sustituir el elemento. El hook aplica el reflejo después de la hidratación. Usa `Edge.Surface` si necesitas incluir sus clases y variables CSS en el HTML del servidor.