Getting Started
hiraku (開く, "to open") is a strongly typed modal state management library for React. It allows you to open modals from anywhere in your application—even outside React components—with full type safety.
Installation
Choose an integration package:
bash
npm install @hirotoshioi/hiraku-radix-ui
npm install @radix-ui/react-dialog @radix-ui/react-alert-dialogbash
npm install @hirotoshioi/hiraku-base-ui
npm install @base-ui/reactTIP
Already using @hirotoshioi/hiraku? It still works, but it’s deprecated and re-exports the Radix UI integration.
For more details, see Packages.
Quick Start
1. Add the Provider
Wrap your application with ModalProvider:
tsx
// app.tsx
import { ModalProvider } from "@hirotoshioi/hiraku-radix-ui";
function App() {
return (
<>
<YourApp />
<ModalProvider/>
</>
);
}2. Create a Modal
Create a modal component and its controller:
tsx
// modals/confirm-dialog.tsx
import { createDialog } from "@hirotoshioi/hiraku-radix-ui";
import {
DialogContent,
DialogHeader,
DialogTitle,
DialogFooter,
} from "@/components/ui/dialog";
import { Button } from "@/components/ui/button";
interface ConfirmDialogProps {
title: string;
message: string;
}
function ConfirmDialog({ title, message }: ConfirmDialogProps) {
return (
<DialogContent>
<DialogHeader>
<DialogTitle>{title}</DialogTitle>
</DialogHeader>
<p>{message}</p>
<DialogFooter>
<Button
variant="outline"
onClick={() => confirmDialog.close({ role: "cancel" })}
>
Cancel
</Button>
<Button
onClick={() => confirmDialog.close({ data: true, role: "confirm" })}
>
Confirm
</Button>
</DialogFooter>
</DialogContent>
);
}
export const confirmDialog = createDialog(ConfirmDialog).returns<boolean>();TIP
You don't need to wrap your component with Dialog.Root—hiraku handles that automatically!
TIP
This Quick Start uses the Radix UI integration. For Base UI, see the example app at examples/base-ui/.
3. Open the Modal
Now you can open the modal from anywhere:
tsx
import { confirmDialog } from "./modals/confirm-dialog";
// Open the modal and wait for the result
const result = await confirmDialog.openAsync({
title: "Delete Item",
message: "Are you sure you want to delete this item?",
});
if (result.role === "confirm" && result.data) {
// User confirmed
deleteItem();
}What's Next?
- Learn why hiraku was created
- Pick an integration package: Packages
- Explore creating different types of modals
- Check out the API reference