ezzy-modal v3.1.9

ezzy-modal

ezzy-modal — This is a minimalist library for creating modal dialogs in React using the native <dialog> element. It weighs only ~1KB, and modal management can be done either through the window object or via a ref, or via useEzzyModal hook, without relying on Redux, Context, or the built-in useState hook.

Features

• Lightweight: — (~1KB, minified + gzipped)
• Ease of Use: — no extra wrappers (Redux/Context)
• Flexible Access: — via window, ref, or hook
• Security: — сustom window access is implemented in a way that cannot be altered, ensuring robust protection against unauthorized modifications.
• Uses <dialog>: — native open/close methods

Installation

# npm
npm install ezzy-modal

Quick Start

1. TypeScript Declarations To allow TypeScript to understand which modals you want to use via the window, create an ezzy-modal.d.tsfile at the root of your project:

import 'ezzy-modal';

interface ModalNames {
  'loginModal': 'Login modal';
}

declare module 'ezzy-modal' {
  export interface EzzyModalExtraNames extends ModalNames {}
}

Here, ModalNames declares your modal identifiers (in the example, it's loginModal). If you need more modals, simply extend this interface:

interface ModalNames {
  loginModal: 'Login modal';
  signupModal: 'Signup modal';
  // ...
}

2. Import and Usage in a React Component

import React, { useRef } from 'react';
import { EzzyModal } from 'ezzy-modal';

function LoginComponent() {
  // A ref to directly access the <dialog> tag
  const ref = useRef < HTMLDialogElement > null;

  // Opening the modal using the ref
  const handleOpenByRef = () => {
    ref.current?.showModal();
  };

  // Opening the modal via window
  const handleOpenByWindow = () => {
    // For this, you need to declare loginModal in ezzy-modal.d.ts, as shown above
    window.ezzyModal.loginModal.showModal();
  };

  return (
    <>
      <button onClick={handleOpenByRef}>Open by ref</button>
      <button onClick={handleOpenByWindow}>Open by window</button>

      <EzzyModal ref={ref} bodyScrollLock closeOnOverlayClick id={'loginModal'}>
        <div style={{ width: '500px', height: '400px' }}>My test modal!</div>
      </EzzyModal>
    </>
  );
}

export default LoginComponent;

2.1 You can also use the useEzzyModal hook which gives you full control over your modal. For example:

import { EzzyModal, useEzzyModal } from './main/ezzy-modal';

export function App() {
  const { open, close } = useEzzyModal('loginModal');

  return (
    <>
      <button onClick={open}>Open by hook</button>

      <EzzyModal bodyScrollLock closeOnOverlayClick id={'loginModal'}>
        <div
          style={{
            width: '500px',
            height: '400px',
          }}
        >
          My test modal!
          <button onClick={close}>Close by hook</button>
        </div>
      </EzzyModal>
    </>
  );
}

Hook Return Value

The useEzzyModal hook returns an object containing:

• open(): void — Opens the modal.
• close(): void — Closes the modal.
• isOpen: boolean — Indicates whether the modal is currently open.

Additionally, the hook accepts a parameter of type ModalNames

EzzyModal Main Props

Below are the key props you can pass to the EzzyModal component:

Additional

• Closing the Modal:

  • Via ref: use ref.current.close()
  • Via window: use window.ezzyModal.[your-modal-name].close()
  • Via hook: just use close()

• Styling:

  • If you want to include the styles, add import 'ezzy-modal/dist/index.css'
  • Use the wrapperClassname prop to assign an additional CSS class to the wrapper.