Quick start

This guide builds a confirmation overlay that resolves a typed result. The runtime does not ship a visual dialog component; instead you register an adapter and let OverlayHost render it when a matching item is opened.

1. Install

npm install @ilokesto/overlay react

2. Create an adapter map

import type { OverlayAdapterMap } from '@ilokesto/overlay';

export const overlayAdapters: OverlayAdapterMap = {
  confirm: ({ close, remove, title, description }) => {
    const finish = (result: boolean) => {
      close(result);
      remove();
    };

    return (
      <div role="dialog" aria-modal="true" aria-labelledby="confirm-title">
        <h2 id="confirm-title">{String(title)}</h2>
        {description ? <p>{String(description)}</p> : null}
        <button onClick={() => finish(true)}>Confirm</button>
        <button onClick={() => finish(false)}>Cancel</button>
      </div>
    );
  },
};

close(result) records the decision and remove() settles the pending promise. This first adapter removes immediately because it has no exit animation. A motion adapter should render while status === 'closing' and call remove() from its transition or animation completion event.

3. Mount the provider

import { OverlayProvider } from '@ilokesto/overlay';
import { overlayAdapters } from './overlay-adapters';
import { DeleteButton } from './delete-button';

export function App() {
  return (
    <OverlayProvider adapters={overlayAdapters}>
      <DeleteButton />
    </OverlayProvider>
  );
}

OverlayProvider creates a provider-scoped store by default and mounts OverlayHost after its children. Everything that calls useOverlay must be inside this provider.

4. Open the overlay

import { useOverlay } from '@ilokesto/overlay';

export function DeleteButton() {
  const { display } = useOverlay();

  async function handleDelete() {
    const confirmed = await display<boolean>({
      type: 'confirm',
      props: {
        title: 'Delete this project?',
        description: 'This action cannot be undone.',
      },
    });

    if (confirmed) console.log('Delete the project');
  }

  return <button onClick={() => void handleDelete()}>Delete</button>;
}

Use display<TResult>() when the caller should wait for a result. Use open() when you only need the generated id and will manage lifecycle separately.

5. Run and verify

Start the React application and select Delete. Selecting Confirm removes the dialog and logs/delegates the deletion path; Cancel removes it without deleting. This example supplies basic dialog semantics but not a focus trap, Escape handling, scroll lock, or visual treatment. Use @ilokesto/modal instead of rebuilding those policies for ordinary dialogs.