Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/src/pages/en/docs/more/with-design-systems/_meta.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,16 @@ export default {
'ant-design': {
title: 'Ant Design',
},
shadcn: {
title: 'shadcn/ui',
},
'radix-ui': {
title: 'Radix UI',
},
mantine: {
title: 'Mantine',
},
'headless-ui': {
title: 'Headless UI',
},
};
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Learn how to use Chakra UI v3's `Dialog` component together with `overlay-kit`.

## Installation

Chakra UI v3 only needs `@emotion/react` (unlike v2, you no longer need `@emotion/styled` or `framer-motion`).
Chakra UI only needs `@emotion/react`.

```sh npm2yarn filename="shell" copy
npm install overlay-kit @chakra-ui/react @emotion/react
Expand Down Expand Up @@ -139,7 +139,7 @@ export function Example() {

## Releasing Memory After Animation

Unlike MUI's `onExited` or Ant Design's `afterClose`, Chakra v3 `Dialog` doesn't expose a dedicated animation-complete callback. The simplest approach is to call `close()` inside `onOpenChange` and schedule `unmount` with `setTimeout` matching the animation duration. This covers button clicks, backdrop clicks, and ESC dismissal uniformly.
Chakra `Dialog` doesn't expose a dedicated animation-complete callback. The simplest approach is to call `close()` inside `onOpenChange` and schedule `unmount` with `setTimeout` matching the animation duration. This covers button clicks, backdrop clicks, and ESC dismissal uniformly.

<br />

Expand Down
252 changes: 252 additions & 0 deletions docs/src/pages/en/docs/more/with-design-systems/headless-ui.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,252 @@
import { Sandpack } from '@/components';

# With Headless UI

Learn how to use Headless UI's `Dialog` component together with `overlay-kit`.

## Installation

Since Headless UI ships unstyled headless primitives, the examples below pair it with Tailwind CSS.

```sh npm2yarn filename="shell" copy
npm install overlay-kit @headlessui/react
```

## Basic Usage

Headless UI `Dialog` takes an `open` prop for visibility and `onClose` for dismissal. `onClose` is invoked automatically on backdrop clicks and Escape key presses, so you can pass `close` directly.

<br />

<Sandpack
dependencies={{
'@headlessui/react': '^2.2.0',
}}
providerOptions={{
externalResources: ['https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4'],
}}
>

```tsx Example.tsx active
import { OverlayProvider, overlay } from 'overlay-kit';
import { Dialog, DialogBackdrop, DialogPanel, DialogTitle, Description } from '@headlessui/react';

function App() {
return (
<button
className="inline-flex items-center justify-center rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-700"
onClick={() => {
overlay.open(({ isOpen, close }) => (
<Dialog open={isOpen} onClose={close} className="relative z-50">
<DialogBackdrop className="fixed inset-0 bg-black/50" />
<div className="fixed inset-0 flex items-center justify-center p-4">
<DialogPanel className="w-full max-w-md space-y-4 rounded-lg bg-white p-6 shadow-xl">
<DialogTitle className="text-lg font-semibold">Are you sure you want to continue?</DialogTitle>
<Description className="text-sm text-gray-500">This action cannot be undone.</Description>
<div className="flex justify-end gap-2">
<button
className="rounded-md border border-gray-200 px-4 py-2 text-sm font-medium hover:bg-gray-100"
onClick={close}
>
No
</button>
<button
className="rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-700"
onClick={close}
>
Yes
</button>
</div>
</DialogPanel>
</div>
</Dialog>
));
}}
>
Open Confirm Dialog
</button>
);
}

export function Example() {
return (
<OverlayProvider>
<App />
</OverlayProvider>
);
}
```

</Sandpack>

## Receiving Async Results

Use `overlay.openAsync` to receive the user's choice as a `Promise`. Pass the result through `close(value)` on each button, and provide a default value in `onClose` for backdrop or Escape dismissal.

<br />

<Sandpack
dependencies={{
'@headlessui/react': '^2.2.0',
}}
providerOptions={{
externalResources: ['https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4'],
}}
>

```tsx Example.tsx active
import { useState } from 'react';
import { OverlayProvider, overlay } from 'overlay-kit';
import { Dialog, DialogBackdrop, DialogPanel, DialogTitle, Description } from '@headlessui/react';

function App() {
const [result, setResult] = useState<boolean | null>(null);

return (
<div>
<p className="mb-2 text-sm">Result: {result === null ? 'Not selected' : result ? 'Yes' : 'No'}</p>
<button
className="inline-flex items-center justify-center rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-700"
onClick={async () => {
const confirmed = await overlay.openAsync<boolean>(({ isOpen, close }) => (
<Dialog open={isOpen} onClose={() => close(false)} className="relative z-50">
<DialogBackdrop className="fixed inset-0 bg-black/50" />
<div className="fixed inset-0 flex items-center justify-center p-4">
<DialogPanel className="w-full max-w-md space-y-4 rounded-lg bg-white p-6 shadow-xl">
<DialogTitle className="text-lg font-semibold">Are you sure you want to continue?</DialogTitle>
<Description className="text-sm text-gray-500">This action cannot be undone.</Description>
<div className="flex justify-end gap-2">
<button
className="rounded-md border border-gray-200 px-4 py-2 text-sm font-medium hover:bg-gray-100"
onClick={() => close(false)}
>
No
</button>
<button
className="rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-700"
onClick={() => close(true)}
>
Yes
</button>
</div>
</DialogPanel>
</div>
</Dialog>
));
setResult(confirmed);
}}
>
Open Confirm Dialog
</button>
</div>
);
}

export function Example() {
return (
<OverlayProvider>
<App />
</OverlayProvider>
);
}
```

</Sandpack>

## Releasing Memory After Animation

Headless UI `Dialog` does not handle transitions on its own and is typically wrapped with `<Transition>`. Passing `unmount` to the `<Transition>`'s `afterLeave` callback releases overlay memory safely right after the close animation finishes.

<br />

<Sandpack
dependencies={{
'@headlessui/react': '^2.2.0',
}}
providerOptions={{
externalResources: ['https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4'],
}}
>

```tsx Example.tsx active
import { Fragment } from 'react';
import { OverlayProvider, overlay } from 'overlay-kit';
import {
Dialog,
DialogBackdrop,
DialogPanel,
DialogTitle,
Description,
Transition,
TransitionChild,
} from '@headlessui/react';

function App() {
return (
<button
className="inline-flex items-center justify-center rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-700"
onClick={() => {
overlay.open(({ isOpen, close, unmount }) => (
<Transition show={isOpen} as={Fragment} afterLeave={unmount}>
<Dialog onClose={close} className="relative z-50">
<TransitionChild
as={Fragment}
enter="ease-out duration-200"
enterFrom="opacity-0"
enterTo="opacity-100"
leave="ease-in duration-150"
leaveFrom="opacity-100"
leaveTo="opacity-0"
>
<DialogBackdrop className="fixed inset-0 bg-black/50" />
</TransitionChild>
<div className="fixed inset-0 flex items-center justify-center p-4">
<TransitionChild
as={Fragment}
enter="ease-out duration-200"
enterFrom="opacity-0 scale-95"
enterTo="opacity-100 scale-100"
leave="ease-in duration-150"
leaveFrom="opacity-100 scale-100"
leaveTo="opacity-0 scale-95"
>
<DialogPanel className="w-full max-w-md space-y-4 rounded-lg bg-white p-6 shadow-xl">
<DialogTitle className="text-lg font-semibold">Are you sure you want to continue?</DialogTitle>
<Description className="text-sm text-gray-500">This action cannot be undone.</Description>
<div className="flex justify-end gap-2">
<button
className="rounded-md border border-gray-200 px-4 py-2 text-sm font-medium hover:bg-gray-100"
onClick={close}
>
No
</button>
<button
className="rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-700"
onClick={close}
>
Yes
</button>
</div>
</DialogPanel>
</TransitionChild>
</div>
</Dialog>
</Transition>
));
}}
>
Open Confirm Dialog
</button>
);
}

export function Example() {
return (
<OverlayProvider>
<App />
</OverlayProvider>
);
}
```

</Sandpack>
Loading
Loading