async-modals v1.0.1

Async Modals

A hook-based way of showing modals in React using promises designed to abstract away the complexity of modal windows.

Interested in contributing to async-modals? Please read the section below on Contributing

Table of Contents

• Quick Start
• Examples
• Usage
  • Options
  • Creating a modal component
  • ModalProvider
  • useModal
• Contributing
• License

To use async-modals install it via npm or yarn

yarn add async-modals

or

npm i async-modals

To start using it:

1. Wrap your app in the ModalProvider Component and import the styles

import React from 'react';
import {ModalProvider} from 'async-modals';
import 'async-modals/dist/style.css';

const App: React.FC = () => {
  return (
    <ModalProvider>
      ...
    </ModalProvider>
  )
}

2. Define a modal component

import React from 'react';

const AlertModal = ({data, submit}) => {
  return (
    <div>
      Alert! {data.message}
      <button onClick={() => submit()}>Dismiss</button>
    </div>
  )
}

3. Use the modal anywhere

import React from 'react';
import {useModal} from 'async-modals'
import AlertModal from './AlertModal'

const Page: React.FC = () => {

  const alertModal = useModal(AlertModal);

  const handleClick = async () => {
    
    //show the modal to the user
    await alertModal.show({
      data: {
        message: 'This is an alert message'
      }
    });
  }

  return (
    <div>
      <button onClick={() => handleClick()}>Show Alert</button>
    </div>
  )
}

These are the options availabe to pass to either ModalProvider or useModal=. You may change the default values of any of these options by passing them to the defaultSettings prop of the modal provider

Below is a simple implementation for a confirmation modal component.

Note that as async-modal doesnt provide any styles for the modal iteself, you will need to provide your own styles or make use of a UI library such as bootstrap or Material UI.

const ConfirmationModal = ({data, submit, cancel}) => {
  <div className="modal">
    <div className="modal-header">
      <h3>Confirm Action</h3>
      <button onClick={cancel}>x</button>
    </div>
      <div className="modal-body">
        {data.message}
      <button onClick={() => submit(false)}>Cancel</button>
      <button onClick={() => submit(true)}>Confirm</button>
    </div>
  </div>
}


export default ConfirmationModal;

A complete list of the props passed into the modal are:

Functions

Basic Usage

import {ModalProvider} from 'async-modals';
import 'async-modals/dist/style.css';

const App: React.FC = () => {
  return (
    <ModalProvider>
      ...
    </ModalProvider>
  )
}

You may also specify default options using the defaultSettings prop

import {ModalProvider} from 'async-modals';
import 'async-modals/dist/style.css';

const App: React.FC = () => {
  return (
    <ModalProvider defaultSettings={{
      animated: true
    }}>
      ...
    </ModalProvider>
  )
}

Basic Usage

import {useModal} from 'async-modals';
import ModalComponent from '../components/ModalComponent';
...

const modal = useModal(ModalComponent)

You can also specify any options here as well

import {useModal} from 'async-modals';
import ModalComponent from '../components/ModalComponent'

...

const modal = useModal(ModalComponent, {
  showBg: false,
  AllowContentScrolling: true,
})

This returns a modal object with the following methods

Below is an example of showing an alert modal with a message being passed in

const modal = useModal(AlertModal);

const showAlert = async () => {
  await modal.show({
    data: {
      message: "This is an alert"
    }
  })
};

You can also await data being returned from a modal component. The below example shows a modal that gets a user's name and then prints it to the console

When receieving data from a modal, it is important to check if it exists before using it. In this instance, if the user exits the modal, name will be undefined

const welcomeModal = useModal(WelcomeModal);

const welcome = async () => {
  const name = await welcomeModal.show()

  if(name){
    console.log(name);
  }
};

The development of this package has mostly been motivated by my own project requirements and use cases. If there is a feature that you would like to see to support your own use cases, please open an Issue or a Pull Request.

MIT Licensed. Copyright (c) Alexander Nicholson 2021.