@faceless-ui/modal

React Modal

An unstyled, transition-ready, a11y-enabled library for creating dialogs, drawers, confirmations, popups, popovers, mega-menus, light-boxes, etc, etc, etc. Meant to power UI libraries. You decide what it does, how it works, how it looks...and ultimately what its called. Build literally any modal experience.

Table of Contents

• Installation
• Basic Setup
• API
• Highlights
• Demo
• Showcase
• Contribution

Quick Start

Installation

$ npm i @faceless-ui/modal
$ # or
$ yarn add @faceless-ui/modal

Basic Setup

import React from 'react';
import {
  Modal,
  ModalContainer,
  ModalProvider,
  ModalToggler
} from '@faceless-ui/modal';

const App = () => (
  <ModalProvider>
    <Modal slug="modal1">
      ...
    </Modal>
    <ModalToggler slug="modal1">
      ...
    </ModalToggler>
    <ModalContainer />
  <ModalProvider>
);

export default App;

Explanation:

• ModalProvider provides context. Render it one-time, at the top-level of your app or nearest common ancestor.

• ModalContainer is where every modal will portal into. Render it one time, anywhere in your app (as a descendant of the provider).

• Modal will new up a modal, it only needs a unique slug.

  • Render as-is, or with render props:

    export default CustomModalB = () => (
      <Modal slug="customModalB">
        {(modal) => {
          const { closeAll } = modal;
    
          return (
            <div>
            ...
              <button onClick={() => closeAll()}>
                Close
              </button>
            </div>
          )
        )}
      </Modal>
    )
    

  • Or instantiate a modal with the asModal HOC:

    export default CustomModalA = asModal((props) => {
      const { closeAll } = props;
    
      return (
        <div>
          ...
          <button onClick={() => closeAll()}>
            Close
          </button>
        <div>
      )
    }, 'customModalA'); // or render with a 'slug' prop
    

• ModalToggler is a quick way to control a modal.

  • You can also toggle a modal directly with the useModal hook:

    export default CustomModalTogglerA = () => {
      const { toggle } = useModal();
    
      return (
        <button onClick={() => toggle('customModalA')}> // or use 'open()'
          Open
        <button>
      )
    };
    

  • Or the withModal HOC:

    export default CustomModalTogglerB = withModal(props) => {
      const { modal: { toggle } } = props;
    
      return (
        <button onClick={() => toggle('customModalB')}> // or use 'open()'
          Open
        <button>
      )
    };
    

API

• asModal
• Modal
• ModalContainer
• ModalProvider
• ModalToggler
• useModal
• withModal

For working examples, see the demo app.

Highlights

• Composable

  Accommodates any setup. Render ModalProvider at the top-level, and ModalContainer anywhere within that. Then create modals and interact with them however your project demands.

• Faceless UI

  Applies no visual style of it's own. CSS transition-ready using react-transition-group. Target any element and any UI state using transition hooks.

• Accessible

  Shipped fully accessible. ModalProvider, asModal, and ModalToggler strictly follow the WAI-ARIA guidelines on modal dialogs. You can also customize anything.

• Agnostic DOM

  Leaves minimal DOM footprint and provides full control. Things like custom markup, accessibility, or additional event handling. Everything beyond core functionality is extendable.

• Router Ready

  Control and be controlled by the URL with any modal. Opt-in to use the native history API. Using Next.js, Gatsby, or some other framework? Easily use those routers too.

Demo

$ git clone [e-mail]:faceless-ui/modal.git
$ yarn
$ yarn dev
$ open http://localhost:3000

Showcase

This package is being actively used in the following projects. To have your project added to this list, please create an issue or make a pull request.

• My290
• Custer Inc
• Payload CMS

Contribution

Help us, or let us help you help us.

License

MIT Copyright (c) TRBL, LLC