Skip to content

Simple is best. Accessible out of the box, tiny api, bring your own styles.

Notifications You must be signed in to change notification settings

itsdouges/react-best-modal

Repository files navigation

react-best-modal

NPM version NPM downloads Build Status codecov

Simple is best. Accessible out of the box, tiny api, bring your own styles. Don't let libraries you use get in the way of what you want, build up, not down. React 16+ only.

Usage

npm install react-focus-lock react-best-modal --save
import React from 'react';
import BestModal from 'react-best-modal';
import { render } from 'react-dom';

const appRoot = document.getElementById('root');

const App = ({ showModal, closeModal }) => (
  <div>
    Hi Mom!
    {showModal && (
      <BestModal onRequestClose={closeModal} appRoot={appRoot}>
        <button>Hello, World!</button>
      </BestModal>
    )}
  </div>
);

render(<App />, appRoot);

NOTE: Make sure you have an element inside your modal that is focusable. Essentially, any input, button, or element with tabIndex="0". This is to ensure focus is set correctly inside the modal - while this isn't enforced, it's strongly advised.

Styling

It's up to you to style and position your modal. Want to disable scrolling content behind your modal? You have to do it yourself. There's an example implementation here.

Transitions

react-best-modal works perfectly with ReactTransitionGroup.

Accessibility

If you're driving home for the ultimate accessible modal, make sure to use aria-labelledby and aria-describedby, for title and description of the modal, like so:

<BestModal
  onRequestClose={closeModal}
  appRoot={appRoot}
  aria-labelledby="modal-title"
  aria-describedby="modal-description"
>
  <button onClick={closeModal}>close</button>
  <h2 id="modal-title">Hello, World!</h2>
  <p id="modal-description">This is a modal, hello worlding!</p>
</BestModal>

Pro tips

  • Have an element that is focusable (for example there is a button above).
  • Make sure to embrace aria-labelledby and aria-describedby.

Focus

  • Focus will be trapped inside the modal when mounted.
  • Focus will automatically jump to the modal's first element when mounted, and will return to the previous focused element when unmounted.

Multiple modals (modals in modals)

This isn't supported. It's also bad practice to show many modals at a time.

API

BestModal

import BestModal from 'react-best-modal';

Props

prop type required description
children ReactNode yes Your modal markup.
onRequestClose (e: KeyboardEvent) => void yes Callback when the modal wants to close. Up to you to action it.
appRoot HTMLElement yes Root of your application. The modal will add and remove accessible attributes when appropriate.
className string no
disableFocusLock boolean no Disables focus lock. Useful if something else wants to trap focus.

All other props that are valid on a HTMLElement are passed through.