# Surface (/product/blocks/surface)



The `surface` block decides where a piece of content appears without the content knowing. A form, a detail panel or a note is written once; whether it opens as a modal dialog, slides in as a side sheet, or navigates to a route of its own is a setting above it.

## Live

Pick a variant, then open the note. The body is the same component in both.

_The surface block renders live on this page._

## Three variants

`dialog` centres a modal over the page. `sheet` slides a panel in from the side. `page` navigates instead of opening anything — the launcher pushes a route, and the modal renders nothing at all, because a page is where the content already lives.

That third one is why the variant is a setting rather than a component choice. A record that a small team edits in a dialog is the same record a large one wants on its own URL, linkable and refreshable. Moving between the two changes one value.

## How it composes

```tsx
const surface = useSurface({ variant, basePath: "/deliveries" });

<SurfaceProvider value={surface}>
  <Button onClick={() => surface.actions.open()}>Open</Button>
  <SurfaceModal title="Delivery note" size="compact">
    <DeliveryNote />
  </SurfaceModal>
</SurfaceProvider>;
```

`useSurface` owns the open state and the navigation. `SurfaceProvider` publishes it. `SurfaceModal` draws the dialog or the sheet, and returns nothing under `page`. The body reads `useSurfaceContext()` when it needs to close itself, and otherwise knows nothing about any of it.

The launcher and the surface are deliberately the same subtree: a sheet mounted on the route it represents would render as a closed panel with nothing left on the page to reopen it.

## Where it is used

The `form` block's modal shell is built on this, which is how one form definition serves an add dialog, an edit sheet and a full page without a second component or a `variant` prop threaded through its fields.

- [All blocks](/product/blocks) — What a block is, what it may import, and how your data reaches it.

- [Form](/product/blocks/form) — Fields, validation, the surface shells and the submit contract.