Introducing Grunfeld

Grunfeld is a lightweight library that makes it easy and consistent to manage dialogs (modals, alerts, confirmations, etc.) in React applications. It's designed to allow you to display dialogs for user interaction and handle results with just a few lines of declarative code, without cumbersome state management or complex control flow.

The core goals are simplicity, accessibility, and extensibility. It supports accessibility considerations by default, such as focus trapping, keyboard dismissal, and ARIA attributes, and allows you to easily change appearance and behavior with custom components, handle multiple modal stacks, integrate animation hooks. It provides a Promise-based API to naturally handle asynchronous flows (e.g., waiting for user decisions in confirmation dialogs).

It also provides TypeScript-friendly type definitions to help you use it safely at compile time, and maintains consistent dialog behavior across your application through the Context/Provider pattern. In server-side rendering (SSR) environments, it's designed to safely render fallback UI, clearly separating client-only logic. It's suitable for teams that want to implement complex dialog scenarios with concise code while maintaining accessibility and maintainability.

Installation#

Grunfeld can be installed in various ways:

npm install @ilokesto/grunfeld
pnpm add @ilokesto/grunfeld
yarn add @ilokesto/grunfeld
bun add @ilokesto/grunfeld

Quick Start#

Add GrunfeldProvider at the top level of your app:

import { GrunfeldProvider } from "@ilokesto/grunfeld";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <GrunfeldProvider>
      <Component {...pageProps} />
    </GrunfeldProvider>
  );
}

Basic Usage#

You can create a simple confirmation dialog and receive the user's response. The grunfeld.add() method returns a Promise, so you can use async/await to wait for the user's choice.

import { grunfeld } from "@ilokesto/grunfeld";

export default function YourComponent() {
  const showConfirmDialog = async () => {
    const result = await grunfeld.add<boolean>((removeWith) => ({
      element: (
        <div>
          <p>Are you sure you want to delete this?</p>
          <button onClick={() => removeWith(true)}>Confirm</button>
          <button onClick={() => removeWith(false)}>Cancel</button>
        </div>
      ),
      position: "center",
      dismissCallback: () => console.log("Dialog closed"),
    }));

    if (result) {
      console.log("User confirmed the action");
    } else {
      console.log("User canceled the action");
    }
  };

  return <button onClick={showConfirmDialog}>Open confirm dialog</button>;
}