Imperative Surface

Imperative Surface is a lightweight, TypeScript-first UI library for React that lets you present dialogs and sheets imperatively and receive the user's result through a Promise.

Instead of keeping modal visibility and result state in the parent component, call a surface and await the result:

import { Surface } from 'imperative-surface';

const confirmed = await Surface.Dialog.present<boolean>({
  body: ConfirmDialog,
});

if (confirmed) {
  console.log('User confirmed');
}

The component rendered inside the surface receives a pop() function. Calling pop(value) closes the surface and resolves the Promise with that value.

Why Imperative Surface?

• Promise-based API — treat UI interactions like asynchronous operations.
• React-first — render normal React components inside dialogs and sheets.
• TypeScript support — type the value returned by a surface.
• Dialog and Sheet — use a centered dialog or an edge-attached sheet.
• Responsive defaults — sheets automatically adapt between desktop and smaller screens.
• CSS customization — override the library's CSS variables without replacing its styling system.
• No provider required — surfaces mount themselves when presented.

Requirements

Imperative Surface declares React and React DOM as peer dependencies and supports React 18+.

Navigation

Start with Installation, then follow Quick Start to present your first surface.