React HTML Dialog

A lightweight React component wrapper for the native HTML <dialog> element. Get accessible, feature-rich modals with minimal code and zero dependencies.

Features

✨ Lightweight - Only ~5KB, uses native <dialog> element
🎯 Zero Dependencies - Just React as a peer dependency
♿ Accessible - Built-in focus trap, ESC key, and ARIA support
🎨 Style Agnostic - Works with any CSS solution
📦 TypeScript - Full type definitions included
🪝 Optional Hook - useDialog hook for state management

Installation

You can install react-html-dialog via npm or yarn:

npm install react-html-dialog

or

yarn add react-html-dialog

How to use

To use the component in your code, you can import the code in your app like this

import { Dialog } from "react-html-dialog";

Then you render the component with the dialog content as the children.

<Dialog open={false} onClose={closeHandler}>
  <h2>Dialog Title</h2>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipisicing elit. A quasi natus quas
    dolore alias optio tenetur perferendis, cupiditate animi ex, omnis quibusdam
    non est, ullam saepe doloremque aperiam quia. Recusandae.
  </p>
  <button>Close Modal</button>
</Dialog>

The component has two required props open and onClose.

open: A boolean indicating whether the dialog is open or closed.

onClose: A callback function to handle closing the dialog.

closeOnClickAway: An optional prop to close the dialog when clicking outside it

This library also provides you with some hooks you might love to use with the Dialog

import { Dialog, useDialog } from "react-html-dialog";

function App() {
  const { open, openDialog, closeDialog } = useDialog();

  return (
    <>
      <button onClick={openDialog}>Open</button>
      <Dialog open={open} onClose={closeDialog}>
        <p>
          Lorem ipsum dolor sit amet, consectetur adipisicing elit. A quasi
          natus quas dolore alias optio tenetur perferendis, cupiditate animi
          ex, omnis quibusdam non est, ullam saepe doloremque aperiam quia.
          Recusandae.
        </p>
        <button onClick={closeDialog}>Close Modal</button>
      </Dialog>
    </>
  );
}

It's not required to use the hooks from the package but if you find it helpful, why not.

Styling

Styling the Dialog component is straightforward since it uses the native <dialog> element:

/* Style the dialog element */
dialog {
  padding: 2rem;
  border: none;
  border-radius: 8px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
}

/* Style the backdrop */
dialog::backdrop {
  background-color: rgba(0, 0, 0, 0.5);
  backdrop-filter: blur(4px);
}

You can also use className prop to add custom classes:

<Dialog open={open} onClose={closeDialog} className="my-custom-dialog">
  {/* content */}
</Dialog>

All CSS solutions work - CSS modules, styled-components, Tailwind, etc.

See usage example on codesandbox

TypeScript

This library is written in TypeScript and includes full type definitions. The DialogProps type is exported for advanced use cases:

import { Dialog, DialogProps, useDialog } from "react-html-dialog";

// Extend DialogProps if needed
type CustomDialogProps = DialogProps & {
  customProp?: string;
};

Browser Support

The native <dialog> element is supported in all modern browsers:

• Chrome/Edge 37+
• Firefox 98+
• Safari 15.4+

For older browsers, consider using a polyfill.

API Documentation

Props for the Dialog Component

| Props | Description | | ------------------ | ------------------------------------------------------------------- | | open | A boolean indicating whether the dialog is open or closed | | onClose | A callback function to handle closing the dialog | | closeOnClickAway | Prop to close the dialog when clicking outside it (on the backdrop) | | ref | A forwarded ref to the <dialog> element | | className | ClassName for the <dialog> element |

Note: All native <dialog> HTML attributes are also supported via spreading.

Available Hooks

useDialog

| Return Values | Description | | ------------- | --------------------------------------------------------- | | open | A boolean indicating whether the dialog is open or closed | | openDialog | A function for setting the open boolean to true | | closeDialog | A function for setting the open boolean to false |

Why react-html-dialog?

• Native & Lightweight - Utilizes the browser's native <dialog> element for optimal performance
• Accessible by Default - Built-in keyboard navigation, focus management, and screen reader support
• Developer Friendly - Simple API with optional useDialog hook for state management
• Framework Agnostic Styling - Works with any CSS solution - modules, styled-components, Tailwind, you name it
• TypeScript First - Full type safety out of the box
• Production Ready - Thoroughly tested and battle-tested in real applications

Support

If you find this library helpful, consider supporting its development:

Contributing

We welcome contributions! Feel free to submit bug fixes, suggestions, or feature enhancements through issues and pull requests.