# React · useSurface

既存の DOM 要素を照明に接続する ref を返します。

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

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

## useSurface(options?)

既存の HTML 要素を最も近い Edge.Provider に接続するコールバック ref を返します。境界線を表示する要素に ref を渡してください。既存の `className` と `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>;
}
```

React 18 の関数コンポーネントでは、`forwardRef` で ref を HTML 要素に渡します。React 19 では ref を prop として受け取ることもできます。

光を明示しない場合は Edge.Provider が必要です。光を直接管理するには、`useLight` が返すハンドルを `useSurface(light, options)` に渡します。明示した光が Edge.Provider の光より優先されます。

| Prop / オプション | 型 | デフォルト | 説明 |
| --- | --- | --- | --- |
| `pseudoElement` | `'after' \| 'before'` | `'after'` | 装飾に使う擬似要素です。既存の ::after を保つには before を選びます。両方が使用済み、またはネイティブ入力の場合はラッパーを使います。不正な値は RangeError を発生させます。 |
| `edgeStyle` | `'raised' \| 'recessed' \| 'matte'` | `'raised'` | 境界が光に反応する方法です。3 つのスタイルはいずれもコンポーネントの外観を維持します。 |
| `color` | `string` | `currentColor` | ハイライトの色です。デフォルトでは DOM 要素の文字色に従います。CSS 変数を含む任意の CSS 色文字列を指定できます。 |
| `shadowColor` | `string` | `#0008` | 反対側の境界の色です。任意の CSS 色文字列を指定できます。明るいサーフェスの影を消すには transparent を使います。 |
| `borderWidth` | `number` | `1` | 装飾の太さをピクセルで指定します。 DOM 要素の境界線は変えません。負数は 0 に制限され、有限でない値はデフォルト値になります。 |
| `intensity` | `number` | `1` | 共有するライトの強度に掛ける値です。有限値は 0〜1 に制限され、有限でない値はデフォルト値になります。 |

1 つの DOM 要素に接続できるライトは 1 つだけです。サイズが異なる親要素に ref を渡さないでください。

オプションを更新しても要素は置き換わりません。フックで接続したハイライトはハイドレーション後に適用されます。サーバー HTML にもクラスと CSS 変数を含めるには、`Edge.Surface` を使います。