Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/davidmfoley/react-router-modal

Simple modals for react-router 4
https://github.com/davidmfoley/react-router-modal

Last synced: about 15 hours ago
JSON representation

Simple modals for react-router 4

Awesome Lists containing this project

README 

        



### Table of Contents



-   [react-router-modal](#react-router-modal)

-   [Accessibility](#accessibility)

-   [Examples](#examples)

-   [ModalContainer](#modalcontainer)

-   [ModalRoute](#modalroute)

-   [Modal](#modal)

-   [ModalLink](#modallink)



## react-router-modal



A simple way to handle showing modals with react-router version 4.



Component docs: 



Examples: 



## Installation



#### Which version of react-router-modal should I use?



TL;DR: If you are using a version of react that is >= 16.3, you should use version 2.



-   react-router-modal version 1 works with react 15.0 and higher

-   react-router-modal version 2 works _only_ with react 16.3 and higher



You can use `yarn info react version` or `npm info react version`, within your project directory, to find the version of react.



Version 2 uses react portals. This makes a few things nicer. The most notable difference is that context that is provided outside of modals works properly within modals.



Because portals are not available on many widely used versions of react, version 2 is currently pre-release.



Install version 1:



`yarn add react-router-modal`



or



`npm install --save react-router-modal`



### Install version 2:



`yarn add react-router-modal@next`



or



`npm install --save react-router-modal@next`



### Other required modules



You also need `react-router-dom`, version 4 or higher.



TBH, if you are looking at this package you probably already have these, but you might want to check for version compatibility.



`react-router-dom` _version 4_



For ex: `yarn add react-router-dom react react-dom`.



### Getting started



To add react-router-modal to your app:



1.  Include the CSS for react-router-modal, found in this package at `css/react-router-modal.css`



If you are using webpack, you can do this:



`import 'react-router-modal/css/react-router-modal.css';`



Note that you can also copy this file or create your own css and specify your own class names.



2.  Add a `` to your react application. This is where any shown modals are added to the DOM.



See also: 



3.  Add a `` to test your setup:



```javascript



  Hello



```



4.  Navigate to /modal-test in your app. You should see a Modal with the contents "Hello".



### Gotchas



#### My modals are not showing at all



1.  Did you render a ModalContainer?



2.  Did you include the CSS to style the modals and their backdrops?



#### I see my modal content but the component "behind" it is not rendering.



To display a modal component "on top" of another component, _both_ routes (the ModalRoute and the Route that renders the other component) must match.



If you are seeing modal content but the component that you expect to see "behind" the modal is not rendering, you should check for the following:



1.  Did you put both routes inside a ``, so only one of them matches?



2.  Did you use `exact` on the `` that contains the component that is meant to render "under" the modal?



## Accessibility



Modals are rendered with the following attributes:



`role="dialog"`



`aria-modal="true"`



### role="dialog"



The role of modals defaults to `dialog`. You can specify a different `role`, for example `alertdialog`:



      FOO;

}



function BarModal() {

  return 
BAR
;

}



function Example() {

 return (

   

     


       show foo

       show bar



       

       



       

     


   

 );

}

```



## ModalContainer



Container for rendered modals.



This should be included in your react app as one of the last elements before the closing body tag.

When modals are rendered, they live inside this container.

When no modals are shown, nothing is rendered into the DOM.



**Parameters**



-   `props` **Props** 

    -   `props.modalClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to modals (optional, default `react-router-modal__modal`)

    -   `props.backdropClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to modal backdrops (optional, default `react-router-modal__backdrop`)

    -   `props.containerClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to the container itself (optional, default `react-router-modal__container`)

    -   `props.bodyModalOpenClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to the  when any modals are shown (optional, default `react-router-modal__modal-open`)

    -   `props.onFirstModalMounted` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** handler invoked when first modal is shown

    -   `props.onLastModalUnmounted` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)?** handler invoked when last modal is hidden

    -   `props.autoRestoreScrollPosition` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Automatically restore the window scroll position when the last modal is unmounted. This is useful in cases where you have made the body position fixed on small screen widths, usually to work around mobaile browser scrolling behavior. Set this to false if you do not want this behavior. (optional, default `true`)

    -   `props.modalInClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to modal immediately after it is shown to allow for css transitions (optional, default `react-router-modal__modal--in`)

    -   `props.modalOutClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to modal before modal is hidden to allow for css transitions (optional, default `react-router-modal__modal--out`)

    -   `props.backdropInClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop immediately after it is shown to allow for css transitions (optional, default `react-router-modal__backdrop--in`)

    -   `props.backdropOutClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop before modal is hidden to allow for css transitions (optional, default `react-router-modal__backdrop--out`)

    -   `props.modalWrapperClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop before modal is hidden to allow for css transitions (optional, default `react-router-modal__wrapper`)

    -   `props.outDelay` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** delay, in milliseconds to wait when closing modal, to allow for css transitions to complete before ripping it out of the DOM (optional, default `0`)



**Examples**



_Using default class names_



```javascript



```



_Overriding the default class names_



```javascript



```



_DOM structure_



```javascript

// Note that modals are made "modal" via CSS styles, and end up rendered like the following in the DOM (with two modals, for example):



  


    


    


      .. bottom-most modal contents ..

    


  


  


    


    


      .. top-most modal contents ..

    


  




```



## ModalRoute



A react-router Route that shows a modal when the location pathname matches.



**Parameters**



-   `routeProps`  

-   `props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

    -   `props.path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** path to match

    -   `props.exact` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If set, only show modal if route exactly matches path.

    -   `props.parentPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** path to navigate to when backdrop is clicked

    -   `props.onBackdropClick` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Handler to invoke when backdrop is clicked. If set, overrides the navigation to parentPath, so you need to handle that yourself.

    -   `props.className` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to modal container

    -   `props.children` **Children** modal content can be specified as chld elements

    -   `props.component` **ReactComponent** modal content can be specified as a component type. The component will be passed `parentPath` and `closeModal` props, in addition to the specified props, and the withRouter props.

    -   `props.props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Props to be passed to the react component specified by the component property.

    -   `props.inClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to modal immediately after it is shown to allow for css transitions (optional, default `react-router-modal__modal--in`)

    -   `props.outClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to modal before modal is hidden to allow for css transitions (optional, default `react-router-modal__modal--out`)

    -   `props.backdropClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop (optional, default `react-router-modal__backdrop`)

    -   `props.backdropInClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop immediately after it is shown to allow for css transitions (optional, default `react-router-modal__backdrop--in`)

    -   `props.backdropOutClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop before modal is hidden to allow for css transitions (optional, default `react-router-modal__backdrop--out`)

    -   `props.outDelay` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** delay, in milliseconds to wait when closing modal, to allow for css transitions to complete before ripping it out of the DOMWhen the route matches, the modal is shown.

        If multiple routes match, the modals will be stacked based on the length of the path that is matched.The component rendered in the modal will receive the following props: (optional, default `0`)

-   `parentPath` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Either the parentPath specified in the ModalRoute, or a calculated value based on matched url

-   `closeModal` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A convenience method to close the modal by navigating to the parentPath



## Modal



Renders its contents in a modal div with a backdrop.

Use Modal if you want to show a modal without changing the route.



The content that is shown is specified by _either_ the "component" prop, or by

child elements of the Modal.



**Parameters**



-   `props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

    -   `props.stackOrder` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** order to stack modals, higher number means "on top"

    -   `props.children` **Children** Modal content can be specified as chld elements

    -   `props.component` **Component** React component to render in the modal.

    -   `props.props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** props to pass to the react component specified by the component property

    -   `props.onBackdropClick` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** handler to be invoked when the modal backdrop is clicked

    -   `props.className` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to modal container

    -   `props.inClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to modal immediately after it is shown to allow for css transitions

    -   `props.outClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to modal before modal is hidden to allow for css transitions

    -   `props.backdropInClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop immediately after it is shown to allow for css transitions

    -   `props.backdropOutClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name applied to backdrop before modal is hidden to allow for css transitions

    -   `props.outDelay` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** delay, in milliseconds to wait when closing modal, to allow for css transitions to complete before ripping it out of the DOM



**Examples**



_Modals using a component and props, vs. child elements_



```javascript

const Hello = ({ who }) => (
Hello {who}!
);



// component and props

const ComponentExample = () => (

  

);



// using child elements

const ChildrenExample = () => (

  

    

  

);

```



_Specifying stack order_



```javascript



  

  



```



## ModalLink



Link and ModalRoute in one convenient component

Renders a link that, when clicked, will navigate to the route that shows the modal.



**Parameters**



-   `props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** 

    -   `props.path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** path to match

    -   `props.exact` **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If set, only show modal if route exactly matches path.

    -   `props.parentPath` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** path to navigate to when backdrop is clicked

    -   `props.linkClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to 

    -   `props.modalClassName` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** class name to apply to modal container

    -   `props.children` **Children** Link contents. Note that Modal content must be specified by the component property.

    -   `props.component` **ReactComponent** Component to render in the modal.

    -   `props.props` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Props to be passed to the react component specified by the component property.



**Examples**



_Example ModalLink_



```javascript



  Say Hello



```