📦 Migrating from @hirotoshioi/hiraku?

If you're using the old package name @hirotoshioi/hiraku, please see the Migration Guide.

Quick summary:

1. npm install @hirotoshioi/hiraku-radix-ui
2. Update imports: from '@hirotoshioi/hiraku' → from '@hirotoshioi/hiraku-radix-ui'
3. Done! (No API changes)

Features

• ⚡ Open from anywhere - Call modal.open() from any file, even outside React components
• 🔒 Type-safe - Strongly typed
• 🎯 Radix UI native - First-class support for Dialog, Sheet, and AlertDialog
• 🪶 Lightweight - ~3KB gzipped, only zustand as dependency
• 🎨 shadcn/ui ready - Works seamlessly with your existing components
• 😃 Migrate with ease - Migrate your existing modals with minimal changes

Installation

npm install @hirotoshioi/hiraku-radix-ui

Radix UI dialog primitives are required as peer dependencies:

npm install @radix-ui/react-dialog @radix-ui/react-alert-dialog

Quick Start

1. Add the Provider

// app.tsx
import { ModalProvider } from "@hirotoshioi/hiraku-radix-ui";

function App() {
  return (
    <>
      <YourApp />
      <ModalProvider/>
    </>
  );
}

2. Create a modal

// modals/confirm-dialog.tsx
import { DialogContent, DialogHeader, DialogTitle, DialogFooter } from "@/components/ui/dialog";
import { Button } from "@/components/ui/button";
import { createDialog } from "@hirotoshioi/hiraku-radix-ui";

interface ConfirmDialogProps {
  title: string;
  message: string;
}

// No need to wrap with Dialog.Root, hiraku will take care of it
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>
  );
}

// Create a modal controller
export const confirmDialog = createDialog(ConfirmDialog).returns<boolean>();

3. Open from anywhere

import { confirmDialog } from "./modals/confirm-dialog";

async function handleDelete() {
  // Open the modal and wait for it
  await confirmDialog.open({
    title: "Delete item?",
    message: "This action cannot be undone.",
  });

  const { data, role } = await confirmDialog.onDidClose();

  if (role === "confirm" && data) {
    // Perform delete
  }
}

Examples

See the full example project in the repository: hiraku Example on GitHub

Or open it in StackBlitz:

API

Factory Functions

| Function | Description | | ------------------------------ | -------------------------------------- | | createDialog(Component) | Create a modal using Radix Dialog | | createSheet(Component) | Create a modal using Radix Sheet | | createAlertDialog(Component) | Create a modal using Radix AlertDialog |

Modal Controller

API for controllers created by createDialog and other factories:

const myModal = createDialog(MyComponent).returns<ResultType>();

// Methods
myModal.open(props)            // Open the modal (returns Promise)
myModal.close({ data, role })  // Close the modal with result
myModal.onDidClose()           // Get Promise that resolves when closed
myModal.isOpen()               // Check if modal is open

useModal Hook

React hook for using modals within components:

import { useModal } from "@hirotoshioi/hiraku-radix-ui";

function MyComponent() {
  const modal = useModal(confirmDialog);

  return (
    <>
      <button onClick={() => modal.open({ title: "Hello" })}>
        Open
      </button>
      <p>isOpen: {modal.isOpen}</p>
      <p>result: {modal.data}</p>
      <p>role: {modal.role}</p>
    </>
  );
}

Global Controller

import { modalController } from "@hirotoshioi/hiraku-radix-ui";

modalController.closeAll()    // Close all open modals
modalController.getCount()    // Get count of open modals
modalController.isOpen()      // Check if any modal is open
modalController.getTop()      // Get the topmost modal

shadcn/ui Integration

hiraku works seamlessly with shadcn/ui components. Just implement Content and below — hiraku manages the Root for you:

import { SheetContent, SheetHeader, SheetTitle } from "@/components/ui/sheet";
import { createSheet } from "@hirotoshioi/hiraku-radix-ui";

function MySheet({ title }: { title: string }) {
  return (
    <SheetContent>
      <SheetHeader>
        <SheetTitle>{title}</SheetTitle>
      </SheetHeader>
      {/* ... */}
    </SheetContent>
  );
}

export const mySheet = createSheet(MySheet);

Why hiraku?

With traditional patterns, modal components are often controlled by their parent for open/close state. That tight coupling hurts readability and maintainability.

If you've built React apps, you've probably seen something like this:

import { MyDialog } from "./MyDialog";
function Parent() {
  // Managing modal state in the parent makes the code cumbersome
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Dialog</button>
      {/* The Dialog has to receive isOpen from the parent */}
      <MyDialog isOpen={isOpen} onClose={() => setIsOpen(false)} />
    </>
  );
}

The modal wants its open/close state managed by the parent, but doing so makes the parent code cumbersome.

hiraku's Approach

hiraku resolves that dilemma. With hiraku, modals can be opened from anywhere in your application without needing to pass down state or handlers through props. This decouples modal logic from your component hierarchy, leading to cleaner and more maintainable code.

import { myDialog } from "./modals/my-dialog";

function Parent() {
  // const [isOpen, setIsOpen] = useState(false); <-- No need to manage state!
  return (
    <>
      <button onClick={() => myDialog.open()}>
        Open Dialog
      </button>
    </>
  );
}

Other UI Frameworks

hiraku is part of a monorepo supporting multiple UI frameworks:

• @hirotoshioi/hiraku-radix-ui - Radix UI implementation (this package)
• @hirotoshioi/hiraku-base-ui - Base UI (MUI) implementation
• @hirotoshioi/hiraku-core - Framework-agnostic core for building custom implementations

License

MIT © Hiroto Shioi