Skip to content

A React library made with Portals for modals, tooltips and popovers.

License

Notifications You must be signed in to change notification settings

bonavida/react-a-gate

Repository files navigation

react-a-gate

version install-size license

Overview

react-a-gate is a React library for modals, tooltips and popovers. It uses the new React feature called Portals. Basically, a portal (ehem... a gate) allows you to render an element of a child component outside the DOM hierarchy by creating another top-level tree and injecting this component inside it.

Demo

If you want to see the library in action, here are some live demos.

Requirements

  • node 12.xx.x
  • npm 6.x.x

Installation

npm install react-a-gate

or

yarn add react-a-gate

Usage

Modal

1 . Import ModalGate after the installation.

import { ModalGate } from 'react-a-gate';

2 . Add the ModalGate component into your JSX code.

const App = () => {
  const [isOpen, setIsOpen] = useState(false);

  const openModal = () => setIsOpen(true);
  const closeModal = () => setIsOpen(false);

  return (
    <>
      <button className="App-button" onClick={openModal}>
        Open modal
      </button>
      <ModalGate id="app_modal" isOpen={isOpen} onClose={closeModal}>
        <>
          <div>This is a modal</div>
          <button className="App-button" onClick={closeModal}>
            Close modal
          </button>
        </>
      </ModalGate>
    </>
  );
};

You can also use a custom React component to be rendered inside the modal, like the example below:

const Text = () => <div>This is some text</div>;

const App = () => {
  // ...
  <ModalGate id="app_modal" isOpen={isOpen} onClose={closeModal}>
    <Text />
  </ModalGate>;
  // ...
};

Props

Property Type Default Description
id String - Identificator for the modal.
Required.
rootId String portal-root Identificator for the portal. If you already have a different root included in your HTML code, just put here the element id. If not, a new one will be created.
className String - Property used to override the default CSS styles with custom ones.
isOpen Boolean false Property used to show and hide the modal.
Required.
closeWhenClickOutside Boolean true Enable or disable the closing of the modal when the user clicks outside.
onClose Function - Function that triggers the closing of the modal. It is used to close the modal when the user clicks outside the modal and when the user pressed the Escape key.
Required.

Tooltip

1 . Import TooltipGate after the installation.

import { TooltipGate } from 'react-a-gate';

2 . Add the TooltipGate component into your JSX code.

const App = () => (
  <TooltipGate content="This is some text" place="top">
    <button className="App-button">Hover me</button>
  </TooltipGate>
);

You can also use a custom React component to be rendered inside the tooltip, like the example below:

const Text = () => <div>This is some text</div>;

const App = () => {
  <TooltipGate content={<Text />} place="top">
    <button className="App-button">Hover me</button>
  </TooltipGate>;
};

Props

Property Type Default Description
rootId String 'portal-root' Identificator for the portal. If you already have a different root included in your HTML code, just put here the element id. If not, a new one will be created.
className String - Property used to override the default CSS styles with custom ones. It also overrides the current selected theme.
content String / JSX Element - Content that will be rendered inside the tooltip. It can be a simple string or a custom React component.
Required.
place String top Property to set where the tooltip will be placed.
Accepted values: top, bottom, left and right.
theme String dark Property to set an already defined theme.
Accepted values: light and dark.
offset Number 10 Distance between the trigger element and the tooltip.
children ReactNode - The trigger element. It can be an HTMLElement or any custom React component.
Required.

Popover

1 . Import PopoverGate after the installation.

import { PopoverGate } from 'react-a-gate';

2 . Add the PopoverGate component into your JSX code.

const App = () => (
  <PopoverGate content="This is some text" place="top">
    <button className="App-button">Click me</button>
  </PopoverGate>
);

You can also use a custom React component to be rendered inside the popover, like the example below:

const Text = () => <div>This is some text</div>;

const App = () => {
  <PopoverGate content={<Text />} place="top">
    <button className="App-button">Click me</button>
  </PopoverGate>;
};

Props

Property Type Default Description
rootId String 'portal-root' Identificator for the portal. If you already have a different root included in your HTML code, just put here the element id. If not, a new one will be created.
className String - Property used to override the default CSS styles with custom ones.
content String / JSX Element - Content that will be rendered inside the popover. It can be a simple string or a custom React component.
Required.
place String top Property to set where the popover will be placed.
Accepted values: top, bottom, left and right.
mode String click Property to set the mode of the popover. 'click' mode will open and close the popover when the user clicks at the trigger element, and the 'hover' mode will open and close the popover when the user hovers in and out the trigger element.
Accepted values: click and hover.
closeWhenClickOutside Boolean true Enable or disable the closing of the popover when the user clicks outside.
theme String dark Property to set an already defined theme.
Accepted values: light and dark.
offset Number 10 Distance between the trigger element and the popover.
children ReactNode - The trigger element. It can be an HTMLElement or any custom React component.
Required.

How to override CSS styles

Each component has a few styles by default. In case you want to override them, here are the main classes you need to override on your project:

Modal

modal__backdrop
  >  modal__content
modal__backdrop--active
  >  modal__content

Tooltip

tooltip__container
tooltip__arrow
tooltip__arrow-border
tooltip__inner

In case you want to customize the colors of the tooltip, here's an example of what you need to do:

.red {
  .tooltip__inner {
    background-color: #ac2121;
    border: 1px solid #700404;
  }

  .tooltip__arrow {
    border-color: #ac2121;
  }

  .tooltip__arrow-border {
    border-color: #700404;
  }
}
<TooltipGate content="This is some text" className="red">
  <button className="App-button">Hover me</button>
</TooltipGate>

Popover

popover__container
popover__arrow
popover__arrow-border
popover__inner

In case you want to customize the colors of the popover, here's an example of what you need to do:

.red {
  .popover__inner {
    background-color: #ac2121;
    border: 1px solid #700404;
  }

  .popover__arrow {
    border-color: #ac2121;
  }

  .popover__arrow-border {
    border-color: #700404;
  }
}
<PopoverGate content="This is some text" className="red">
  <button className="App-button">Click me</button>
</PopoverGate>