Eze-Spark

Eze-Spark is a versatile library for creating and managing customizable popups in your React applications. It offers a simple API and various configuration options to make your popups look and behave just the way you want.

Installation

You can easily install Eze-Spark via npm or yarn:

npm install eze-spark
# or
yarn add eze-spark

Quick Start

Set up the ProviderContainer component in your main application file (e.g., App.js or App.tsx):

import "./App.css"
import { ProviderContainer } from 'eze-spark';

const App = () => {
  return (
    <>
      {/* Your app code... */}
      <ProviderContainer />
    </>
  );
};

export default App;

Now you can use the PopupMe function to create popups anywhere in your application:

The PopupMe function takes two arguments: the first argument is the component that you want to render inside the popup it can be a React component or a function that returns a React component, and the second argument is an object containing the popup's options. You can find more information about the available options in the Popup Options section.

Create PopupExample.js or PopupExample.tsx and add this code to it:

import { PopupMe } from 'eze-spark';

const PopupExample = () => {
  return (
    <div className="test-container">
      <p className="test-button" onClick={() => PopupMe(<PopupChild />)}>
        Open Popup
      </p>
    </div>
  );
};

export default PopupExample;

const PopupChild = () => {
  return (
    <div className="test-col">
      <p className="test-label-red"> Hello World </p>
    </div>
  );
};

Include the PopupExample component in your main application file to see the result:

import "./App.css"
import React from "react";
import { ProviderContainer } from 'eze-spark';
import PopupExample from "./PopupExample";

const App = () => {
  return (
    <>
      {/* Your app code... */}
      <PopupExample />
      <ProviderContainer />
    </>
  );
};

export default App;

The result should look like this:

Examples

Popup with a custom component and props

import { PopupMe } from 'eze-spark';

const PopupExample = () => {
  const [title, setTitle] = React.useState("Am I a popup?");
  return (
    <div className="test-container">
      <input className="test-input" value={title} onChange={(e) => setTitle(e.target.value)} />
      <p className="test-button" onClick={() => PopupMe(<PopupChild title={title} />)}>
        Open Popup
      </p>
    </div>
  );
};

export default PopupExample;

const PopupChild = ({ title }: PopupChildProps) => {
  return (
    <div className="test-col">
      <p className="test-label-red"> {title} </p>
    </div>
  );
};

interface PopupChildProps {
  title: string;
}

The result should look like this:

Popup with a custom component and a target

import { PopupMe } from 'eze-spark';

const PopupExample = () => {
  return (
    <div className="test-container">
      <p className="test-button" onClick={(e) => PopupMe(<PopupChild title="Am Relative to body " />)}>
        Relative to body
      </p>
      <p
        className="test-button"
        onClick={(e) =>
          PopupMe(<PopupChild title={"Am Relative to target"} />, {
            target: e.target as any,
          })
        }>
        Relative to me
      </p>
    </div>
  );
};

export default PopupExample;

const PopupChild = ({ title }: PopupChildProps) => {
  return (
    <div className="test-col min-w-max">
      <p className="test-label-red"> {title} </p>
    </div>
  );
};

interface PopupChildProps {
  title: string;
}

The result should look like this:

Popup with a custom component and an animation

import { PopupMe } from 'eze-spark';

const animations = [
  "auto",
  "width",
  "height",
  "width-height",
  "scale-x",
  "scale-y",
  "scale-both",
  "slide-bottom",
  "slide-top",
  "slide-left",
  "slide-right",
  "fade",
  "none",
];

const PopupExample = () => {
  const [animation, setAnimation] = React.useState<any>("auto");

  return (
    <div className="test-container">
      <p className="test-label-gray">
        Current Animtaion is: <span className="test-label-red"> {animation} </span>
      </p>

      <div className="test-wrap">
        {animations.map((anim) => (
          <div className={`test-button ${animation === anim ? "" : "bg-white"}`} key={anim} onClick={() => setAnimation(anim)}>
            {anim}
          </div>
        ))}
      </div>

      <p className="test-button" onClick={(e) => PopupMe(<PopupChild animation={animation} />, { target: e.target as any, animation })}>
        Relative to me
      </p>

      <p className="test-button" onClick={() => PopupMe(<PopupChild animation={animation} />, { animation })}>
        Relative to body
      </p>
    </div>
  );
};

export default PopupExample;

const PopupChild = ({ animation }: PopupChildProps) => {
  return (
    <div className="test-col min-w-max">
      <p className="test-label-red">
        <span className="test-label-gray">animation: </span>
        {animation}
      </p>
    </div>
  );
};

interface PopupChildProps {
  animation: string;
}

The result should look like this:

Popup with a custom component and a placement

import { PopupMe } from 'eze-spark';

const placementsWithBody = ["auto", "center", "top", "top-left", "top-right", "bottom", "bottom-left", "bottom-right", "left", "right", "none"];

const PopupExample = () => {
  const [placement, setPlacement] = React.useState<any>("auto");
  return (
    <div className="test-container">
      <h1 className="test-label-gray">Placements with target</h1>
      <div className="test-wrap gap">
        {placementsWithBody.map((plac: any) => (
          <div
            className={`test-button ${placement === plac ? "" : "bg-white"}`}
            key={plac}
            onClick={() => {
              setPlacement(plac);
              PopupMe(<PopupChild placement={plac} />, { placement: plac });
            }}>
            {plac}
          </div>
        ))}
      </div>
    </div>
  );
};

export default PopupExample;

const PopupChild = ({ placement }: PopupChildProps) => {
  return (
    <div className="test-col min-w-max">
      <p className="test-label-red" style={{ textAlign: "center" }}>
        <span className="test-label-gray"> placement: </span>
        {placement}
      </p>
    </div>
  );
};

interface PopupChildProps {
  placement: string;
}

The result should look like this:

Popup with a custom component and a placement

import { PopupMe } from 'eze-spark';

const placementsWithTarget = ["auto", "left", "top", "top-left", "top-right", "bottom", "bottom-left", "bottom-right", "right", "none", "auto"];

const PopupExample = () => {
  const [placement, setPlacement] = React.useState<any>("auto");
  return (
    <div className="test-container">
      <h1 className="test-label-gray">Placements with target</h1>
      <div
        className={`test-button ${placement === "inside" ? "" : "bg-white"}`}
        key={"inside"}
        onClick={(e) => {
          setPlacement("inside");
          PopupMe(<PopupChild placement={"inside"} />, { target: e.target as any, placement: "inside" });
        }}>
        {"inside"}
      </div>
      <div className="test-wrap gap">
        {placementsWithTarget.map((plac: any) => (
          <div
            className={`test-button ${placement === plac ? "" : "bg-white"}`}
            key={plac}
            onClick={(e) => {
              setPlacement(plac);
              PopupMe(<PopupChild placement={plac} />, { target: e.target as any, placement: plac });
            }}>
            {plac}
          </div>
        ))}
      </div>
    </div>
  );
};

export default PopupExample;

const PopupChild = ({ placement }: PopupChildProps) => {
  return (
    <div className="test-col min-w-max">
      <p className="test-label-red">
        <span className="test-label-gray"> placement: </span>
        {placement}
      </p>
    </div>
  );
};

interface PopupChildProps {
  placement: string;
}

The result should look like this:

Configuration

You can configure the ProviderContainer component by passing the following props to it:

Name	Type	Default	Description
containerClass	string	""	The class name of the popup container.
childClass	string	""	The class name of the popup's child.
overlayClass	string	""	The class name of the popup's overlay.
offset	object	{x:0,y:0}	The offset of the popup.
animationTime	number	300	The animation time of the popup.
clearOnNavigation	boolean	true	Whether to clear all popups when the user navigates to another page.

Popup Options

You can configure each popup by passing the following options to the PopupMe function:

Name	Type	Default	Description
id	string	global	The id of the popup. If not provided, a random id will be generated.
placement	string	auto	The placement of the popup. It can be one of the following: auto, inside, center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right, none.
target	Element	body	The target element of the popup. If not provided, the popup will be rendered relative to the body.
overlay	boolean	true	Whether to render an overlay behind the popup.
componentProps	any	null	The props to be passed to the component.
removeOnOutClick	boolean	true	Whether to remove the popup when the user clicks outside of it.
offset	object	{x:0,y:0}	The offset of the popup.
viewPort	object	window	The viewport of the popup.
childClass	string	""	The class name of the popup's child.
onRemoved	function	null	A function to be called when the popup is removed.
containerClass	string	""	The class name of the popup's container.
animation	string	auto	The animation of the popup. It can be one of the following: auto, width, height, width-height, scale-x, scale-y, scale-both, slide-bottom, slide-top, slide-left, slide-right, fade, none.

Animations

Eze-Spark comes with a set of predefined animations that you can use to animate your popups. You can also create your own animations by adding new CSS classes to the library's CSS file.

Name	Description
auto	The default animation. It is the same as width-height.
width	The popup's width will be animated.
height	The popup's height will be animated.
width-height	The popup's width and height will be animated.
scale-x	The popup's width will be animated.
scale-y	The popup's height will be animated.
scale-both	The popup's width and height will be animated.
slide-bottom	The popup will slide from the bottom.
slide-top	The popup will slide from the top.
slide-left	The popup will slide from the left.
slide-right	The popup will slide from the right.
fade	The popup will fade in and out.

API

PopupMe

PopupMe(Component: PopupComponentType, options: PopupOptions = {})

PopupMe is the main function of the library. It takes a React component and renders it as a popup. It returns a function that can be used to remove the popup.

Popup

Popup: PopupController

Popup is the main controller of the library. It has the following properties:

Name	Type	Default	Description
create	function	null	A function to create a popup.
remove	function	null	A function to remove a popup.
removeAll	function	null	A function to remove all popups.
getPopup	function	null	A function to get a popup by its id.
getPopups	function	null	A function to get all popups.
getPopupIds	function	null	A function to get all popup ids.

PrintMe

PrintMe(props: PrintProps)

PrintMe is a function that prints a component. It takes the following props:

Name	Type	Default	Description
Component	React.ReactNode	null	The component to be printed.
componentProps	any	null	The props to be passed to the component.
afterPrint	function	null	A function to be called after the component is printed.

What dose it do?

It create the component in a hidden div and wait for all images to be loaded then disable every child in the body except the provided component and print the component and enable all children again.

So you don't need to worry about the images and other elements in the body and you can print the component without any problem.

You don't need to build a print page and you can print the component in the same page.

Authors

Owl

Support

If you have any questions or need assistance, please reach out to Owl or open an issue on GitHub.