npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-marketing-popups

v1.2.2

Published

Animated React popouts, banners and slide-ins with timer, scroll, inactivity, exit-intent and persistence hooks

Readme

react-marketing-popups

Marketing popups for React without rebuilding triggers, animations and persistence.

Create animated popouts, announcement banners and slide-in campaigns triggered by time, scroll depth, inactivity or exit intent.

Live Demo · Storybook · npm · Report a Bug · Request a Feature

Popout

Why this library?

Marketing experiences often begin with a modal and gradually turn into a custom system.

You install a modal or positioning library, then implement:

  • entrance and exit animations;
  • timer, scroll and exit-intent behaviour;
  • dismissal and conversion state;
  • localStorage persistence;
  • announcement banners and slide-ins;
  • campaign-specific styling.

react-marketing-popups brings those pieces together in one React library while keeping your content, styling and open state under your control.

Use it for:

  • newsletter and lead-capture forms;
  • product announcements;
  • limited-time offers and discounts;
  • exit-intent campaigns;
  • onboarding messages;
  • feature promotions;
  • upsells and cross-sells;
  • event and maintenance notices.

What is included?

| Capability | Included | | ----------------------------------- | ------------------------------------------ | | Centred modal popouts | Popout | | Top, bottom, left and right banners | Banner | | Left and right slide-in panels | SlideIn | | Timed campaigns | useTimerTrigger | | Scroll-depth campaigns | useScrollTrigger | | Inactivity campaigns | useInactivityTrigger | | Exit-intent campaigns | useExitTrigger | | “Show once” behaviour | useTriggerPersistence | | Manual persistence control | usePersistence | | Built-in animations | Fade, zoom, slide and bounce | | Styling control | CSS imports, class names and element props | | TypeScript declarations | Included | | Component-level imports | Included |

Installation

npm install react-marketing-popups
# or
yarn add react-marketing-popups

Quick start

Display a marketing popout three seconds after the page loads:

import { useState } from "react";
import {
  Popout,
  useTimerTrigger
} from "react-marketing-popups";
import "react-marketing-popups/Popout/style.css";

export function DiscountPopout() {
  const [open, setOpen] = useState(false);

  useTimerTrigger({
    ms: 3000,
    onOpenChange: setOpen
  });

  return (
    <Popout
      id="welcome-discount"
      open={open}
      onOpenChange={setOpen}
      animation="zoom"
      lockScroll
    >
      <div style={{ padding: 24 }}>
        <h2>Get 10% off your first order</h2>
        <p>Join our mailing list to receive your discount code.</p>

        <button type="button">
          Get my discount
        </button>
      </div>
    </Popout>
  );
}

That gives you:

  • a controlled React popout;
  • a three-second trigger;
  • built-in entrance and exit animation;
  • overlay dismissal;
  • body-scroll locking;
  • fully custom content.

Show a campaign only once

Combine a trigger with useTriggerPersistence to prevent the same campaign from appearing repeatedly.

import { useState } from "react";
import {
  Popout,
  useTimerTrigger,
  useTriggerPersistence
} from "react-marketing-popups";
import "react-marketing-popups/Popout/style.css";

export function PersistentDiscountPopout() {
  const [open, setOpen] = useState(false);
  const [claimed, setClaimed] = useState(false);

  const [fired] = useTimerTrigger({
    ms: 3000,
    onOpenChange: setOpen
  });

  const { hasSeen } = useTriggerPersistence({
    id: "first-order-discount",
    fired,
    open,
    isOk: claimed
  });

  return (
    <Popout
      id="first-order-discount"
      open={open && !hasSeen()}
      onOpenChange={setOpen}
      isOk={claimed}
      closeOnOk
    >
      <div style={{ padding: 24 }}>
        <h2>Get 10% off your first order</h2>

        <button
          type="button"
          onClick={() => setClaimed(true)}
        >
          Claim offer
        </button>
      </div>
    </Popout>
  );
}

The campaign is marked as seen when the visitor:

  • completes the desired action; or
  • closes the popup after its trigger has fired.

Components

All three components are controlled through open and onOpenChange. You decide when they appear and what they contain.

Popout

A centred modal for offers, forms, announcements and confirmations.

import { useState } from "react";
import { Popout } from "react-marketing-popups";
import "react-marketing-popups/Popout/style.css";

export function NewsletterPopout() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button
        type="button"
        onClick={() => setOpen(true)}
      >
        Join newsletter
      </button>

      <Popout
        id="newsletter"
        open={open}
        onOpenChange={setOpen}
        animation="zoom"
        closeOnOverlay
      >
        <div style={{ padding: 24 }}>
          <h2>Join the newsletter</h2>
          <p>Receive product news and practical guides.</p>
        </div>
      </Popout>
    </>
  );
}

Popout props

| Prop | Type | Default | Description | | ------------------ | ------------------------------ | -------- | ------------------------------------ | | lockScroll | boolean | false | Prevents body scrolling while open. | | closeOnOverlay | boolean | true | Closes when the overlay is selected. | | animation | "fade" \| "zoom" \| "bounce" | "zoom" | Entrance and exit animation. | | overlayClassName | string | — | Class for the overlay. | | contentClassName | string | — | Class for the content container. | | elemProps | object | — | HTML props for internal elements. |

Banner

A horizontal or vertical banner for announcements, promotions and notices.

import { Banner } from "react-marketing-popups";
import "react-marketing-popups/Banner/style.css";

export function ShippingBanner() {
  return (
    <Banner
      id="free-shipping"
      open
      onOpenChange={() => undefined}
      position="top"
      animation="slide"
    >
      Free delivery on orders placed today.
    </Banner>
  );
}

Banner props

| Prop | Type | Default | Description | | -------------------- | ---------------------------------------- | ---------- | --------------------------------- | | position | "top" \| "bottom" \| "left" \| "right" | "bottom" | Banner placement. | | animation | "fade" \| "slide" \| "bounce" | "slide" | Entrance and exit animation. | | containerClassName | string | — | Class for the root element. | | contentClassName | string | — | Class for the content element. | | elemProps | object | — | HTML props for internal elements. |

SlideIn

A fixed panel that enters from either side of the viewport.

import { SlideIn } from "react-marketing-popups";
import "react-marketing-popups/SlideIn/style.css";

export function FeatureAnnouncement({
  open,
  setOpen
}: {
  open: boolean;
  setOpen: (open: boolean) => void;
}) {
  return (
    <SlideIn
      id="feature-announcement"
      open={open}
      onOpenChange={setOpen}
      position="right"
      animation="slide"
    >
      <div style={{ padding: 24 }}>
        <h2>A new feature is available</h2>
        <p>Explore the latest addition to your dashboard.</p>
      </div>
    </SlideIn>
  );
}

SlideIn props

| Prop | Type | Default | Description | | -------------------- | ------------------------------- | --------- | --------------------------------- | | position | "left" \| "right" | "left" | Side from which the panel enters. | | animation | "fade" \| "slide" \| "bounce" | "slide" | Entrance and exit animation. | | wrapperClassName | string | — | Class for the root wrapper. | | containerClassName | string | — | Class for the panel container. | | contentClassName | string | — | Class for the content element. | | elemProps | object | — | HTML props for internal elements. |

Shared component props

| Prop | Type | Default | Description | | ------------------- | ------------------------- | -------- | -------------------------------------------- | | id | string | Required | Unique campaign or persistence key. | | open | boolean | Required | Controls visibility. | | onOpenChange | (open: boolean) => void | Required | Receives visibility changes. | | children | ReactNode | Required | Content rendered inside the component. | | isOk | boolean | false | Indicates that the desired action succeeded. | | closeOnOk | boolean | false | Closes when isOk becomes true. | | duration | number | 300 | Animation duration in milliseconds. | | closeBtnClassname | string | — | Class for the close button. |

Behavioural triggers

Each trigger calls onOpenChange(true) when its condition is met and returns its fired state.

Time delay

useTimerTrigger({
  ms: 5000,
  onOpenChange: setOpen
});

Useful for welcome offers, newsletter prompts and delayed announcements.

| Option | Type | Default | | -------------- | ------------------------- | ------- | | ms | number | 3000 | | onOpenChange | (open: boolean) => void | No-op |

Scroll depth

useScrollTrigger({
  percent: 60,
  onOpenChange: setOpen
});

Useful for showing a call to action after someone has engaged with an article or landing page.

| Option | Type | Default | | -------------- | ------------------------- | ------- | | percent | number | 50 | | onOpenChange | (open: boolean) => void | No-op |

Inactivity

useInactivityTrigger({
  ms: 15000,
  onOpenChange: setOpen
});

Useful for assistance messages, reminders and re-engagement campaigns.

| Option | Type | Default | | -------------- | ------------------------- | ------- | | ms | number | 30000 | | onOpenChange | (open: boolean) => void | No-op |

Exit intent

useExitTrigger({
  topZonePx: 50,
  delayMs: 200,
  once: true,
  onOpenChange: setOpen
});

Useful for last-chance offers and abandonment campaigns on pointer-based devices.

| Option | Type | Default | | -------------- | ------------------------- | ------- | | topZonePx | number | 50 | | delayMs | number | 0 | | once | boolean | true | | onOpenChange | (open: boolean) => void | No-op |

Persistence

useTriggerPersistence

Use this with one of the behavioural triggers.

const [fired] = useScrollTrigger({
  percent: 50,
  onOpenChange: setOpen
});

const {
  hasSeen,
  markSeen,
  clear
} = useTriggerPersistence({
  id: "article-newsletter",
  fired,
  open,
  isOk: subscribed
});

| Option | Type | Description | | ------- | --------- | ----------------------------------------- | | id | string | Unique persistence key. | | fired | boolean | Fired state returned by a trigger. | | open | boolean | Current component state. | | isOk | boolean | Whether the desired action was completed. |

Returns:

| Value | Description | | ------------ | -------------------------------------------------- | | hasSeen() | Checks whether the campaign has already been seen. | | markSeen() | Marks the campaign as seen. | | clear() | Clears its stored state. |

usePersistence

Use the lower-level persistence hook when you want complete manual control.

const {
  hasSeen,
  markSeen,
  clear
} = usePersistence("product-announcement");
<Banner
  id="product-announcement"
  open={open && !hasSeen()}
  onOpenChange={setOpen}
>
  <button
    type="button"
    onClick={() => {
      markSeen();
      setOpen(false);
    }}
  >
    Dismiss
  </button>
</Banner>

Styling

Components include built-in CSS, but their content and styling remain customisable.

Import every component style

import "react-marketing-popups/style.css";

Import only what you use

Component-level CSS imports are recommended:

import "react-marketing-popups/Popout/style.css";
import "react-marketing-popups/Banner/style.css";
import "react-marketing-popups/SlideIn/style.css";

Import the required stylesheet once near your application entry point.

For example:

// main.tsx or pages/_app.tsx
import "react-marketing-popups/Popout/style.css";
import "./app.css";

Your application stylesheet can then override the library defaults.

.my-offer-popout {
  border-radius: 1rem;
  max-width: 32rem;
}

.my-offer-close-button {
  font-size: 1.25rem;
}
<Popout
  id="my-offer"
  open={open}
  onOpenChange={setOpen}
  contentClassName="my-offer-popout"
  closeBtnClassname="my-offer-close-button"
>
  Your content
</Popout>

You can also pass HTML attributes to the underlying elements through each component's elemProps API.

Component-level imports

The package exposes individual components and hooks for more focused imports.

import { Popout } from "react-marketing-popups/Popout";
import { useExitTrigger } from "react-marketing-popups/hooks/useExitTrigger";
import "react-marketing-popups/Popout/style.css";

Available component entry points:

react-marketing-popups/Banner
react-marketing-popups/Popout
react-marketing-popups/SlideIn

Available hook entry points:

react-marketing-popups/hooks/useTimerTrigger
react-marketing-popups/hooks/useScrollTrigger
react-marketing-popups/hooks/useInactivityTrigger
react-marketing-popups/hooks/useExitTrigger
react-marketing-popups/hooks/useTriggerPersistence
react-marketing-popups/hooks/usePersistence

Examples by use case

The library can be composed for several common marketing experiences:

| Use case | Suggested combination | | --------------------------- | --------------------------------------- | | Delayed newsletter form | Popout + useTimerTrigger | | Article subscription prompt | SlideIn + useScrollTrigger | | Exit discount | Popout + useExitTrigger | | Product announcement | Banner + usePersistence | | Inactive-user assistance | SlideIn + useInactivityTrigger | | One-time onboarding message | Any component + useTriggerPersistence |

Explore working variations in the live demo and Storybook.

Why not use a general modal library?

General modal and positioning libraries are useful foundations. They normally focus on rendering, focus management or positioning.

react-marketing-popups focuses on the layer above those primitives:

  • campaign-oriented display components;
  • marketing-specific behavioural triggers;
  • repeat-display prevention;
  • built-in animation options;
  • a consistent API across popouts, banners and slide-ins.

Use a lower-level primitive when you need to build every interaction yourself. Use this package when you need a reusable marketing-popup system.

Roadmap

Possible future additions include:

  • additional campaign templates;
  • analytics event hooks;
  • frequency and time-based display limits;
  • mobile-specific triggers;
  • campaign prioritisation;
  • additional animation options;
  • more framework integration examples.

Have a use case that is missing? Open a feature request.

Feedback and production usage

Using react-marketing-popups in a project?

Please consider:

Real-world examples and feedback help determine what should be built next.

Contributing

Issues and pull requests are welcome.

Good ways to contribute include:

  • reproducing or fixing a bug;
  • improving documentation;
  • adding tests;
  • creating a new Storybook example;
  • proposing an integration example;
  • improving a component or trigger API.

To run the project locally:

git clone https://github.com/oluyoung/react-marketing-popups.git
cd react-marketing-popups
npm install
npm run storybook

Run the test suite:

npm test

Create a production build:

npm run build

Before beginning a larger change, open an issue so the proposed approach can be discussed.

Interested in helping maintain the project? Open an issue describing the areas you would like to work on.

Licence

This project is licensed under the ISC License.