React-clean-modal

A minimal modal plugin for React and very easy to use.

Live examples • Key Features • How To Use • Documentation • Credits • Contributing • License • Contact

Live examples

You can see code examples here.
You can see live demo here.

Key Features

• Modal Portal: insert your own content inside the modal
• Custom buttons: Use array with your buttons (event handling available)
• Custom footer: add a footer with your button and align them
• Close: with icon on top, on overlay click or/and on mouse scroll
• Animations: Overlay fade-in and modal show-up
• Custom props: add aria-label, data-testid, and custom css classes

How To Use

To use the modal plugin:

# in your project root terminal
$ npm i react-clean-modal

Contributing/Fork : you'll need Git and Node.js (which comes with npm) installed on your computer. From your command line:

# Install dependencies
$ npm install

# Run the app
$ npm run start

Documentation

Import Modal component and the hook useModal. Props isVisible and hide are required.

import React from 'react'
import { Modal, useModal } from 'react-clean-modal'

function App() {
    const { isShowing: showModal, toggle: toggleModal } = useModal()
    return (
        <>
            <button type="button" className="btn" onClick={toggleModal}>
                Open me!
            </button>

            <Modal isVisible={showModal} hide={toggleModal}>
                // Your content
                <h1>Title</h1>
                <div>Content</div>
                <button type="button" className="btn-clean-modal" onClick={toggleModal}>
                    Close me!
                </button>
            </Modal>
        </>
    )
}

Custom footer

You can pass an array with button (custom classes, content and event function) to display a modal footer.

import React from 'react'
import { Modal, useModal } from 'react-clean-modal'

function App() {
    const { isShowing: showModal, toggle: toggleModal } = useModal()

    const customEvent = () => {
        alert('Ah')
    }
    const arrayOfBtn = [
        {
            text: 'Close modal',
            className: 'btn-clean-modal'
        },
        {
            text: 'Alert me!',
            className: 'btn-clean-modal',
            eventHandling: customEvent
        }
    ]
    return (
        <>
            <button type="button" className="btn" onClick={toggleModal}>
                Open me!
            </button>

            <ReactCleanModal
                isVisible={showModal}
                hide={toggleModal}
                customFooter={arrayOfBtn}
                customFooterAlign={'left'}>
                // Your content
                <h1>Title</h1>
                <div>Content</div>
            </ReactCleanModal>
        </>
    )
}

Waiting with spinner

You can show a spinner when you waiting for async function. the modal toggle will hide spinner automatically. In your function, launch spinner, get data and launch modal.

import React from 'react'
import { Modal, useModal } from 'react-clean-modal'

function App() {
    const {
        isShowing: showModal,
        toggle: toggleModal,
        isShowingSpinner: showSpinner,
        toggleSpinner: toggleSpinner
    } = useModal()

    const launchModalTimer = () => {
        toggleSpinner()

        setTimeout(() => {
            toggleClassicModal()
        }, 3000)
    }

    return (
        <>
            <button type="button" className="btn" onClick={launchModalTimer}>
                Open me!
            </button>

            <ReactCleanModal isVisible={showModal} hide={toggleModal} showSpinner={showSpinner}>
                // Your content
                <h1>Title</h1>
                <div>Content</div>
            </ReactCleanModal>
        </>
    )
}

All props

Prop	Type	Required?	Default	Description
isVisible	boolean	required	false	Event handler for modal (custom hook).
hide	function	required	Hook to toggle modal	Event handler for modal (custom hook).
animations	boolean	optional	false	true: fade-in and show-up animation.
ariaLabelledBy	string	optional	-	ariaLabelledBy={'aria-label'} set in the modal container, linked with your own title.
closeOnOverlayClick	boolean	optional	false	true: Modal will close on overlay click.
closeOnScroll	boolean	optional	false	true: Modal will close on mouse scroll.
closeOnTop	boolean	optional	false	true: Icon on right top displayed for close modal.
customClass	string	optional	-	Add a custom class to all HTML class attributes for override styles.
customFooter	Array.Object	optional	-	Add your buttons with proper event to the modal footer.
customFooterAlign	string	optional	'center'	Align your buttons array ('left', 'center','right').
testId	string	optional	-	Add data-testid attribute to the modal container for tests.
showSpinner	boolean	optional	false	Update modal display with custom hook. See example above.

Credits

This software uses the following open source packages:

• React
• Babel/core
• SASS
• ESLint
• Prettier
• Testing-library
• istanbul-badges-readme
• jest-html-reporter
• Enzyme

Contribute

You want to contribute ?

You can read this: CONTRIBUTING.md. Contributors wanted :)

Contact

Audrey Diez - @Linkedin - audrey.diez@gmail.com