Farmblocks Modal

A React Modal component

Table of Contents

• Installation
• Usage
• API
• Helpers
  • useModal
  • ModalManager
• Extra Components
  • DialogModal
  • ModalTitle
• License

Installation

npm install @crave/farmblocks-modal

Usage

import React from "react";
import { render } from "react-dom";
import Modal from "@crave/farmblocks-modal";

const App = () => (
  <div>
    This is the regular content
    <Modal isOpen>This is the modal content</Modal>
  </div>
);

render(<App />, document.getElementById("root"));

This code will render:

API

• isOpen (Boolean) = false

  Whether the modal is visible or not.

• verticalAlign (Array || String) = ["flex-end", "flex-start"]

  Vertical position of the modal at the viewport. All justify-content values are valid.

• parentNode (HTMLElement) = document.body

  Element in which the modal should be attached. Can be either inside or outside the ReactDOM root but not the same element.

• shouldCloseOnOverlayClick (Boolean) = true

  Whether onRequestClose should be called or not when the overlay is clicked.

• shouldCloseOnEsc (Boolean) = true

  Whether onRequestClose should be called or not when the ESC key is pressed.

• showCloseButton (Boolean) = true

  Whether the close button should be visible or not. When visible, it will be rendered inside the header section whether there's a header or not.

• onRequestClose (Function)

  Function to call when the overlay or close icon are clicked, or the ESC key is pressed.
  It passes either a MouseEvent or a KeyboardEvent depending on the action.

• onOpen (Function)

  Function to call when the modal opens.

• onClose (Function)

  Function to call when the modal closes.

• cardProps (Object)

  Props to be passed to the Card component that wraps the modal.

• closeButtonProps (Object)

  Props to be passed to the Button component used for the close button.

• zIndex (Number) = 1500

  Value for the z-index CSS property.

• header (Node)

  Node for the header section

• footer (Node)

  Node for the footer section

• footerProps (Object)

  Properties passed to the footer section

Helpers

useModal

The Modal component is stateless. So the visibility is controlled exclusively by the isOpen prop, and the close actions (close icon, overlay click and ESC key) won't change it automatically. You need to create a function for onRequestClose that will handle the state and change the isOpen prop accordingly.

The useModal hook helps to manage the state for the component. It will return 2 objects:

• props, containing isOpen and onRequestClose properly bound to a useState.
• actions, containing the open, close and toggle functions that can be used inside or outside the modal.

import Modal, { useModal } from "@crave/farmblocks-modal";

const Example = () => {
  const [myModalProps, { open, close }] = useModal();

  return (
    <>
      <button onClick={open}>Open Modal</button>
      <Modal footer={<button onClick={close}>Close</button>} {...myModalProps}>
        This is the a modal.
      </Modal>
    </>
  );
};

Optionally, it can receive an options object:

const [props, actions] = useModal({ openAtMount: true });

• openAtMount (Boolean) = false

  The initial state for the isOpen prop.

ModalManager

A class component version of useModal. It expects a function as the children prop and passes the hook results as arguments.

import Modal, { ModalManager } from "@crave/farmblocks-modal";

const Example = () => (
  <ModalManager>
    {(myModalProps, { open }) => (
      <>
        <button onClick={open}>Open Modal</button>
        <Modal {...myModalProps}>This is the a modal.</Modal>
      </>
    )}
  </ModalManager>
);

Extra Components

DialogModal

This is a combination of the Modal and the Empty State Components. It accepts all the props from both of them.

import { DialogModal } from "@crave/farmblocks-modal";
import { MdAlert } from "@crave/farmblocks-icon";

const Example = () => (
  <DialogModal
    isOpen
    icon={<MdAlert />}
    title="Delete entry?"
    description="This action can't be undone"
    actions={[
      {
        text: "Cancel",
        type: buttonTypes.NEUTRAL,
        onClick: () => console.log("Canceled"),
      },
      {
        text: "Delete",
        type: buttonTypes.PRIMARY,
        onClick: () => console.log("Deleted"),
      },
    ]}
  />
);

ModalTitle

Component to use on header prop, is a Text with font-weight: 600 and font-size: 24px as default, and accepts all the Text properties.

import { DialogModal } from "@crave/farmblocks-modal";

const Example = () => (
  <Modal isOpen header={<ModalTitle>Header</ModalTitle>}>
    Modal using <strong>ModalTitle</strong> on header
  </Modal>
);

Peer dependencies

• prop-types
• react
• react-dom
• react-spring
• styled-components
• styled-system

License

MIT