@faceless-ui/modal

America's next top modal

Usage no npm install needed!

<script type="module">
  import facelessUiModal from 'https://cdn.skypack.dev/@faceless-ui/modal';
</script>

README

NPM Bundle Size Supported by TRBL

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

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

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 git@github.com: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.

Contribution

Help us, or let us help you help us.

License

MIT Copyright (c) TRBL, LLC