# React · Edge.Surface

Applies lighting to a DOM element.

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

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

## Edge.Surface

Renders one HTML element connected to the nearest provider. Native attributes and events follow the tag selected by `as`.

```tsx
<Edge.Surface as="article" edgeStyle="raised">
  Your content
</Edge.Surface>
```

| 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. |
| `as` | `HTML tag name` | `'div'` | The HTML element to render. Native attributes and the ref follow the chosen tag; custom React components are not accepted here. |
| `children` | `ReactNode` | `Unset` | Content rendered inside the element. Use a wrapper for inputs and other elements that cannot display the decoration themselves. |
| `ref` | `Ref<HTMLElement for the chosen tag>` | `Unset` | Forwarded to the rendered element alongside the internal registration ref. React 19 callback-ref cleanup is preserved. |
| `className` | `string` | `Unset` | Your classes, combined with the decoration classes. |
| `style` | `CSSProperties` | `Unset` | Your inline styles, merged after the decoration bindings. Keep Edge-owned CSS variables intact unless deliberately overriding them. |

Place every `Edge.Surface` inside a `Edge.Provider` owner; rendering it outside one throws an error. For native inputs and occupied pseudo-elements, see [Integration considerations](https://edge.bolerish.com/docs/integration/).

Decoration aligns with the outside of the element's border. To connect an existing component’s HTML element, use [useSurface](https://edge.bolerish.com/docs/react/use-surface/#use-surface).