What is Dialogist?

Dialogist is a centralized dialog manager for React apps: one provider, hooks from anywhere, no prop drilling. It's built with a style/component-agnostic core (plus MUI-friendly defaults), and uses slot-based updates so titles, content, actions, and the dialog backplane can refresh independently without re-rendering the entire component tree.

Screenshots

Features

• One DialogProvider, dialogs opened from any component
• Synchronous and Promise-based open() for async flows
• Slot registry and hooks for state-reactive re-rendering
• Dialog keys to uniquely identify and track dialog instances
• Conflict policies to handle overlapping opens
• TypeScript-first API

Install

npm install dialogist

Package version: 1.0.0

Peer dependencies: react >=18.0.0 and react-dom >=18.0.0

If you are using MUI and its theming system (recommended), add peer dependencies: @mui/material v7+, Emotion (@emotion/react, @emotion/styled).

Quick start

import { DialogProvider, useDialog } from "dialogist";

function App() {
  return (
    <DialogProvider>
      <MyComponent />
    </DialogProvider>
  );
}

function MyComponent() {
  const dialog = useDialog("delete-item");

  const handleDelete = async () => {
    const event = await dialog.open({
      type: "confirm",
      title: "Delete item",
      message: "This action cannot be undone.",
      okLabel: "Delete",
      cancelLabel: "Cancel",
    });

    if (event.ok) {
      // Confirmed
    }
  };

  return <button onClick={handleDelete}>Delete item</button>;
}

Demo and documentation

Documentation and a comprehensive set of examples for Dialogist is at https://brandonscript.github.io/dialogist/ — it is the best place to explore Dialogist interactively.

Run the demo locally

The demo is a Next.js app in demo/nextjs, and can also be run locally. From the repository root:

npm install
cd demo/nextjs && npm install && cd ../..
npm run demo:nextjs

Open http://localhost:5607 in your browser. The demo:nextjs script starts the Next.js dev server for demo/nextjs on port 5607 by default.

Contributing

Human contributors: see AGENTS.md for project conventions, testing, and layout rules. While primarily written with LLMs in mind, it's good for humans too.

Issues and pull requests are welcome. For larger changes, open an issue first so we can align on direction. Please run all tests (add/update tests to ensure coverage of your changes) and update the demo app if applicable. All code accepted to main must be reviewed by you, the human.

If you contribute to this project, you agree to adhere to the

Publishing (maintainers)

1. Bump the version (updates root package.json, package-lock.json, and the Package version line in this readme):

   ./scripts/version.sh X.Y.Z

2. Sanity-check tests, types, and what would be published:

   npm test
   npm run typecheck
   npm run release:dry-run

   Extra npm publish flags go after --, for example npm run release -- --dry-run --tag beta.

   Avoid naming an npm script publish: npm publish runs the package publish lifecycle and would recurse into that script.

3. Publish when logged into npm with permission to publish dialogist:

   npm run release

4. Tag and release on GitHub (after the version bump is on main):

   git tag -a vX.Y.Z -m "vX.Y.Z"
   git push origin main --follow-tags
   gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes

Fair AI and LLM usage

AI contributors: see AGENTS.md for project conventions, testing, and layout rules.

If you use AI tools with this codebase or its documentation: do not submit generated changes without reviewing them yourself by hand for correctness, security, and fit with project conventions.

License

MIT

Ethical use

Per the Hippocratic License 3.0, you may not use, copy, modify, or employ this project's source code to cause harm or in any way violate internationally recognized human rights.