React Ease Modal

A simple, modular, and customizable modal component for React applications. Compatible with Tailwind CSS, it provides flexible modal management with various styling and accessibility options.

Table of Contents

• Installation
• Compatibility and Dependencies
• Usage
• Properties
• Styles
• Accessibility
• Demonstration
• License

Installation

To install react-ease-modal in your React project, run one of the following commands:

npm install react-ease-modal

or

yarn add react-ease-modal

Compatibility and Dependencies

Dependencies

react-ease-modal does not rely on any external libraries to function.

Compatibility

• React: Compatible with React 17+ and React 18+.
• Tailwind CSS (optional): While Tailwind is not required, you can use it to style the modal.
• CSS: You can use your own CSS classes for additional customization.

Usage

To use react-ease-modal and its subcomponents, import them into your React file and integrate them into your JSX:

import { useState } from 'react';
import { Modal, ModalContent, ModalClose, ModalDescription, ModalFooter, ModalHeader, ModalTitle } from 'react-ease-modal';

function App() {
    const [isOpen, setIsOpen] = useState(false);

    return (
        <main>
            <button className="btn btn-primary" onClick={() => setIsOpen(true)}>
                Open Modal
            </button>
            <Modal open={isOpen}>
                <ModalContent>
                    <ModalClose onClose={() => setIsOpen(false)} />
                    <ModalHeader>
                        <ModalTitle>Modal Title</ModalTitle>
                        <ModalDescription>This is the modal content.</ModalDescription>
                    </ModalHeader>
                    <ModalFooter>
                        <button className="btn btn-secondary" onClick={() => setIsOpen(false)}>
                            Close Modal
                        </button>
                    </ModalFooter>
                </ModalContent>
            </Modal>
        </main>
    );
}

export default App;

Properties

Modal

| Property | Type | Required | Description | | ----------------- | ----------- | -------- | -------------------------------------------------------------------------------------- | | className | string | Optional | Custom CSS class(es) to apply to the modal. | | open | boolean | Yes | Indicates if the modal is open or closed. | | children | ReactNode | Yes | Content to display inside the modal. | | ariaLabelledBy | string | Optional | ID of the element defining the modal title for the aria-labelledby attribute. | | ariaDescribedBy | string | Optional | ID of the element defining the modal description for the aria-describedby attribute. |

ModalContent

| Property | Type | Required | Description | | ----------- | ----------- | -------- | ----------------------------------------------------------- | | className | string | Optional | Custom CSS class(es) to apply to the modal content. | | children | ReactNode | Yes | Content to display inside the modal. | | ariaLabel | string | Optional | Label for the aria-label attribute for the modal content. |

ModalClose

| Property | Type | Required | Description | | ----------- | ---------- | -------- | -------------------------------------------------------- | | className | string | Optional | Custom CSS class(es) to apply to the modal close icon. | | onClose | function | Yes | Callback function triggered to close the modal. | | ariaLabel | string | Optional | Label for the aria-label attribute for the close icon. |

ModalHeader

| Property | Type | Required | Description | | ----------- | ----------- | -------- | ---------------------------------------------------------- | | className | string | Optional | Custom CSS class(es) to apply to the modal header. | | children | ReactNode | Yes | Content to display inside the modal header. | | ariaLabel | string | Optional | Label for the aria-label attribute for the modal header. |

ModalTitle

| Property | Type | Required | Description | | ----------- | ----------- | -------- | --------------------------------------------------------------------------- | | className | string | Optional | Custom CSS class(es) to apply to the modal title. | | children | ReactNode | Yes | Title to display inside the modal. | | id | string | Optional | ID used for the aria-labelledby attribute to link the title to the modal. |

ModalDescription

| Property | Type | Required | Description | | ----------- | ----------- | -------- | ---------------------------------------------------------------------------------- | | className | string | Optional | Custom CSS class(es) to apply to the modal description. | | children | ReactNode | Yes | Description to display inside the modal. | | id | string | Optional | ID used for the aria-describedby attribute to link the description to the modal. |

ModalFooter

| Property | Type | Required | Description | | ----------- | ----------- | -------- | ---------------------------------------------------------- | | className | string | Optional | Custom CSS class(es) to apply to the modal footer. | | children | ReactNode | Yes | Content to display inside the modal footer. | | ariaLabel | string | Optional | Label for the aria-label attribute for the modal footer. |

Styles

react-ease-modal allows you to add custom styles via the className prop of each subcomponent.

Example with Custom Styles

import { useState } from 'react';
import { Modal, ModalContent, ModalClose, ModalDescription, ModalFooter, ModalHeader, ModalTitle } from 'react-ease-modal';
import './styles/global.css'; // Your custom CSS file

function App() {
    const [isOpen, setIsOpen] = useState(false);

    return (
        <main>
            <button className="btn btn-primary" onClick={() => setIsOpen(true)}>
                Open Modal
            </button>
            <Modal className="modal-overlay" open={isOpen}>
                <ModalContent className="modal-container">
                    <ModalClose className="modal-icon" onClose={() => setIsOpen(false)} />
                    <img className="modal-hero" src="./hero.svg" alt="hero" />
                    <ModalHeader className="modal-header">
                        <ModalTitle className="modal-title">Modal Title</ModalTitle>
                        <ModalDescription className="modal-description">This is the modal content.</ModalDescription>
                    </ModalHeader>
                    <ModalFooter className="modal-footer">
                        <button className="btn btn-secondary" onClick={() => setIsOpen(false)}>
                            Close Modal
                        </button>
                    </ModalFooter>
                </ModalContent>
            </Modal>
        </main>
    );
}

export default App;

Sample CSS File

/* Basic styles */
main {
    height: 100%;
    display: flex;
    align-items: center;
    justify-content: center;
}

.btn {
    border-radius: 2rem;
    transition: background-color 0.4s, border 0.4s;
}

.btn-primary {
    background-color: #e2e2e2;
    color: #536cb4;
    padding: 1rem 2rem;
}

.btn-primary:hover {
    background-color: transparent;
    color: #e2e2e2;
}

.modal-overlay {
    position: absolute;
    z-index: 999;
    display: flex;
    align-items: center;
    justify-content: center;
    background-color: rgba(0, 0, 0, 0.5);
    width: 100%;
    height: 100%;
    top: 0;
    left: 0;
}

.modal-container {
    background-color: #323232;
    border-radius: 0.8rem;
    padding: 1.5rem;
    width: 450px;
    box-shadow: rgba(0, 0, 0, 0.3) 2px 2px 6px;
}

.modal-header {
    text-align: center;
    padding-bottom: 1rem;
}

.modal-title {
    color: #e2e2e2;
    margin: 1rem 0;
}

.modal-description {
    color: #bebebe;
}

.modal-footer {
    display: flex;
    justify-content: center;
    padding-top: 1rem;
    border-top: 1px solid #bebebe;
}

Accessibility

The Modal component includes several features aimed at enhancing accessibility:

• Identification as a dialog: Use of the role="dialog" attribute to indicate that the modal window is a dialog, improving the experience for screen reader users.

• Managing background content: The aria-modal="true" attribute signals to assistive technologies that the content behind the modal is not accessible while it is open.

• Contextual descriptions:

  • The aria-labelledby and aria-describedby attributes provide additional descriptions:
    • aria-labelledby associates an element, such as a modal title, with the dialog so that the title is announced.
    • aria-describedby links a description to the dialog, offering additional context to users.

• Focus management: The tabIndex="-1" attribute is added to ensure that the modal receives focus when the user navigates via the keyboard.

• Accessibility of the close button: The close button includes an aria-label attribute to describe its function to screen reader users.

• Additional aria-label attributes: Components and subcomponents may also include aria-label attributes to provide contextual descriptions.

These best practices enhance interaction with the modal for users of assistive technologies and promote an inclusive user experience.

Example

import { useState } from 'react';
import { Modal, ModalContent, ModalClose, ModalDescription, ModalFooter, ModalHeader, ModalTitle } from 'react-ease-modal';

function App() {
    const [isOpen, setIsOpen] = useState(false);

    return (
        <main>
            <button className="btn btn-primary" onClick={() => setIsOpen(true)}>
                Open Modal
            </button>
            <Modal className="modal-overlay" open={isOpen} ariaLabelledBy="modal-title" ariaDescribedBy="modal-description">
                <ModalContent className="modal-container">
                    <ModalClose className="modal-icon" onClose={() => setIsOpen(false)} ariaLabel="Close modal" />
                    <img className="modal-hero" src="./hero.svg" alt="hero" />
                    <ModalHeader className="modal-header">
                        <ModalTitle className="modal-title" id="modal-title">
                            Modal Title
                        </ModalTitle>
                        <ModalDescription className="modal-description" id="modal-description">
                            This is the modal content.
                        </ModalDescription>
                    </ModalHeader>
                    <ModalFooter className="modal-footer">
                        <button className="btn btn-secondary" onClick={() => setIsOpen(false)}>
                            Close Modal
                        </button>
                    </ModalFooter>
                </ModalContent>
            </Modal>
        </main>
    );
}

export default App;

Demonstration

You can see the demo of this component at the following address: https://aeonshad.github.io/react-ease-modal/

The source code is available at this address: https://github.com/aeonshad/react-ease-modal

License

This project is licensed under the MIT license.