react-modal-queue

Raise modal dialogs and views from any JavaScript code in a React application. This package is different from other React modal packages because it does not require a component in every location that a modal needs to appear, instead a single ModalProvider is used to display modals.

Advantages

• Does not require a React component in every location where a modal needs to appear, instead a single ModalProvider at the base of the application is used to display modals.
• Triggering the display of a modal can be done from any code in the application and is not restricted to React components; for example a long-running background process encounters a problem and needs to display an error.
• A single DOM location for the appearance of modals simplifies styling and animating modals.

Examples

A basic JavaScript and CSS implementation to display the modal above the page contents. Demonstrates using ModalProvider and raiseModal.

A more complex example that demonstrates animating the appearance and disappearance of the modal using react-transition-group and CSS.

Install

npm i -S react-modal-queue

Use

Typically you will just wrap your application in the ModalProvider component.

import { ModalProvider } from "react-modal-queue";

export default = props => {
    return (
        <ModalProvider>
            <App {...props} />
        </ModalProvider>
    );
};

When you need to display a modal use raiseModal(). This function takes a single argument: an instance of ModalOptions with information about the modal, and returns a function that can be used to dismiss the modal when it is no longer needed.

import { raiseModal } from "react-modal-queue";

export default = props => {

    const raiseModal = () => {
        const dismissModal = raiseModal({
            body: "You raised a modal!",
            footer: () => dismissModal(),
            title: "Modal Title",
            uid: "MODAL_EXAMPLE"
        });
    };
    
    return (
        <button onClick={raiseModal}>Display Modal</button>
    );

};

Title

The title content can be a string that will be placed into an <h1> element or a React Component if the title needs to be customized.

Body

A modal's body content can be created simply by providing a single string or an array of strings. Each string will be surrounded by a <p> element. If more customization is needed a React Component can be provided for the body.

Footer

A set of buttons can be displayed in the modal's footer. There are three different options for defining the footer: one or two buttons can be displayed by passing handler functions, a set of button definitions can be provided in an array, or a React Component can be provided as the footer content.

Style and Appearance

The ModalProvider adds and removes elements from the document's DOM to display a modal. The appearance of those elements as a "modal UI control" depends entirely on the CSS that is applied to them. When a modal is created it will look like this in the DOM (the contents of title, body, and footer will vary depending on the props set) and will appear after the contents of ModalProvider.

<div class="modal-queue-overlay visible">
    <div class="modal-queue-container visible">
        <div class="modal-queue visible">
            <span aria-hidden="true" style="visibility: collapse;"><!-- providerUid: '1553865290781', modalUid: 'MODAL_EXAMPLE' --></span>
            <div class="modal-queue-title">
                <h1>Modal Title</h1>
            </div>
            <div class="modal-queue-body">
                <p>You raised a modal!</p>
            </div>
            <div class="modal-queue-footer">
                <button class="modal-queue-button affirmative"></button>
            </div>
        </div>
    </div>
</div>

For these elements to appear as a modal - above the page contents, and in normal use as only dismissable by clicking a button - CSS must be applied. There is an example that illustrates the modal styled with the behavior described.

Notes

Modal requests are queued and processed in the order they are received. Only one modal is displayed at a time.

Showing and hiding the modal can be animated using the react-transition-group package. Wrap the component in a transition component and the transition classes will be set on the modal-queue-overlay element.

If ModalOptions.dismissable is set to true or to an OnDismissableModalDismissed function then the modal can be dismissed if the user clicks anywhere outside the modal.

TypeScript declaration files are included and should be available for code completion (e.g. VS Code) when the package is included through an import statement.

To include the package in the head of an HTML document use UNPKG. There are two files available, a production version named "react-modal-queue.min.js" and a debug version "react-modal-queue.js".

API

The ModalProvider allows an application to display modals. This component is placed at the root of an application and is reponsible for controlling modals.

|Prop|Type|Description| |---|---|---| |[uid]|string|Optional unique identifier for this modal provider that can be used to direct a modal request to a specific provider instance.| |[children]|JSX.Element | JSX.Element[]|Optional components between ModalProvider opening and closing tags.|

A function returned by raiseModal. When invoked it dismisses the raised modal. Takes no parameters and returns void.

Invoke this function to display a modal.

|Parameter|Type|Description| |---|---|---| |options|ModalOptions|The options for the modal.|

Returns DismissModal A function to dismiss the modal that was raised.

Information displayed in the main content of a modal.

|Property|Type|Description| |---|---|---| |content|string | string[] | JSX.Element|The main content can be one or more strings, or a component. Strings will be placed inside <p> elements.|

Props to configure the bottom portion of the modal.

|Property|Type|Description| |---|---|---| |content|ModalFooterButtonHandlerProps | ModalFooterButtonProps[] | JSX.Element|The contents of the footer.|

Allows simple and semi-custom buttons to be created in the footer.

|Property|Type|Description| |---|---|---| |[className]|string|Optional class name that will be set on the button. |content|string | JSX.Element|The information that will be displayed as the contents of a button element.| |[focus = false]|boolean|Optional if true the button will be focused. This should be true for only one button in the array.| |[onClick]|(props: ModalFooterButtonProps) => void|Optional handler that will be invoked when the button is clicked.

The simplest way to create a footer with one or two buttons, simply add handlers for the corresponding buttons.

|Property|Type|Description| |---|---|---| |onAffirmativeClick|OnClickHandler|Invoked when the affirmative button is clicked.| |[onNegativeClick]|OnClickHandler|Optional handler for a negative response button. If not supplied the button will not appear.| |[primary]|"affirmative" | "negative"|Optional toggle to set the class "primary" on one of the two buttons.|

Object that controls the display of a modal.

|Property|Type|Description| |---|---|---| |body|string | string[] | ModalBodyProps|The information to display in the main part of the modal.| |[dismissable = false]|boolean | OnDismissableModalDismissed|Optional if true the modal can be dismissed by clicking outside of the modal.| |[footer]|OnClickHandler | [OnClickHandler, OnClickHandler] | ModalFooterProps|Optional information displayed at the bottom of the modal. For a single affirmative button (i.e. "OK") pass a single OnClickHandler. For two buttons, one affirmative and one negative (i.e. "OK, "Cancel") pass an array with two OnClickHandlers. For more control use ModalFooterProps.| |[providerUid]|string|Optional unique identifier of the provider.| |[title]|string | ModalTitleProps|Optional title to display at the top of the modal.| |uid|string|A unique identifier for this modal. Only one modal with this unique identifier can be queued at a time.|

Data used to display the title of a modal.

|Property|Type|Description| |---|---|---| |content|string | JSX.Element|The information to display in the title. A string will be displayed as the content of an <h1> element.|

A function invoked when a button is clicked. Takes no parameters and returns void.

A function that is invoked by a modal to indicate that the user has clicked outside of a dismissable modal. This function should be provided if the disappearance of the modal is animated and the function creator needs to start that animation. Takes no parameters and returns void.