@usemodals/react

the eaist way to open/close modals and pass props to modals, or register an dynmaic modal and you can use these modals globally, for React

If you are looking for documentation for obsolete react-modal-better-hooks@1, please, check this branch.

Install

npm install @usemodals/react

QuickStart

• Wrap app entry with ModalProvider

  import { ModalProvider } from '@usemodals/react'

  export default () => {
    return (
      <div>      
        <ModalProvider defaultProps={{
          width: '500px',
          centered: true
        }}>
          <AppComponnet />
        </ModalProvider>
      </div>
    )
  }

API

useRegisterModal

This hooks is used to register the modals, register modals by calling the hooks

• Parameters

    useRegisterModal(modals)

  | name | description | default | | ------------------- | ------------------------------------------------------------ | ------- | | modals | It's an object where the object key is the modalId and the value is the configuration of the modal you want to register | {} | | modalId.component | the modal Component | NA | | modalId.isLazy | specify current modal is a lazy modal | false | | modalId.loader | lazy modal loader | NA |

• Useage

  import { useRegisterModal } from '@usemodals/react'

  import Modal1 from 'path/to/modal1'

  const Page = () => {
    useRegisterModal({
      modal1: {
        component: modal1
      },
      modal2: {
        isLazy: true,
        loader: () => import('path/to/modal2')
      }
    })

    return (
      <>
        {/* page logic */}
      </>
    )
  }

useOpenModal

This hooks is used to open modal, it returns a function to open modal, and open modal by calling the function

• Parameters

    openModal(modalId, props)

  | name | description | default | | ------- | --------------------------------------------------------- | ------- | | modalId | the id corresponding to the modal that needs to be opened | NA | | props | the props that need to be passed into the modal component | {} |

• Useage

  import { useOpenModal } from '@usemodals/react'

  interface ModalProps {
    title: string
    content: string
  }

  const Page = () => {
    const openModal = useOpenModal<ModalPropsInterface>()

    return (
      <>
        <div onClick={() => openModal('idOfModalToOpen', {
          title: 'modalTitle',
          content: 'modalContent'
        })}></div>
      </>
    )
  }

useCloseModal

This hooks is used to close modal or close all modals, it returns a function named closeModal to close modal, and the function to close all modals is called closeAllModals

• Parameters

    const { closeModal } = useCloseModal()
  
    closeModal('modalId')

  | name | description | default | | ------- | --------------------------------------------------------- | ------- | | modalId | the id corresponding to the modal that needs to be closed | NA |

• Useage

    import { useCloseModal } from '@usemodals/react'
  
    const Page = () => {
      const { closeModal, closeAllModals } = useCloseModal()
        
      return (
        <>
          <div onClick={() => closeModal('idOfModalToClose')}>close one modal</div>
          <div onClick={closeAllModals}>close all modals</div>
        </>
      )
    }

useUpdateModal

The props of the modal are not necessarily completely unchanged, so if you need to update a certain modal props, you can use this hooks, which return a function, the parameters are similar to openModal, and there is an property merge to specify whether to merge the previous props

• Parameters

  import { useUpdateModal } from '@usemodals/react'
  
  const updateModal = useUpdateModal()
  updateModal(modalId, config)

  | name | description | default | | ------- | --------------------------------------------------------- | ------- | | modalId | the id corresponding to the modal that needs to be opened | NA | | config.props | the props that need to be passed into the modal component | NA | | config.merge | if it's true, old props will be merged, otherwise, will override old props | false |

• Usage

    import { useUpdateModal, useOpenModal } from '@usemodals/react'
  
    interface ModalProps {
      title: string
      content: string
    }
  
    const Page = () => {
      const openModal = useOpenModal<ModalPropsInterface>()
      const updateModal = useUpdateModal<ModalPropsInterface>()
        
      return (
        <>
          <div onClick={() => {
            openModal('idOfModalToOpen', {
              title: 'modalTitle',
              content: 'modalContent'
            })
              
            /**
              * the modal's props will be 
              * { title: 'newModalTitle', content: 'modalContent' }
              * during second render
              */
            setTimeOut(() => {
              updateModal('idOfModalToUpdate', {
                title: 'newModalTitle'
              }, true)
            }, 5000)
              
            /**
              * the modal's props will be 
              * { title: 'newModalTitle', content: 'newModalContent' }
              * during second render
              */
            setTimeOut(() => {
              updateModal('idOfModalToUpdate', {
                title: 'newModalTitle',
                content: 'newModalContent'
              })
            }, 10000)
          }}>open and update modal</div>
        </>
      )
    }

useModalProps

This hooks is used to get modal props, it returns a function, and get modal props by calling the function

• Usage

  import { useModalProps } from '@usemodals/react'
  
  const getModalProps = useModalProps()
  const props = getModalProps(modalId)

useModalIsLoading

This hooks is used to determine whether modal or modals is loading and returns a boolean, if the modal is not registered or the modal is not a LazyModal, it will always return false

• Usage

    import { useModalIsLoading } from '@usemodals/react'
  
    const Page = () => {
      //	returns true when either modal1 or modal2 is loading
      const isLoading = useModalIsLoading(['modal1', 'modal2'])
        
      //	only reutrn modal1 loading state
      const isLoading2 = useModalIsLoading('modal1')
        
      return (
        <>
        </>
      )
    }

Motivation

• reduce unnecessary business code
• easier to controll modal display/hidden or update modals' props
• common modal props

For detail demo, check here