useSurface

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

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.

useSurface signature

const ref = useSurface<HTMLElement>(options);

Share one light with existing components

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.

useSurface options
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.