react-marketing-popups
v1.2.2
Published
Animated React popouts, banners and slide-ins with timer, scroll, inactivity, exit-intent and persistence hooks
Maintainers
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

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;
localStoragepersistence;- 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-popupsQuick 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/SlideInAvailable 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/usePersistenceExamples 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:
- starring the repository;
- opening an issue with feedback;
- sharing the type of campaign you built;
- suggesting an example or integration you would find useful.
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 storybookRun the test suite:
npm testCreate a production build:
npm run buildBefore 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.
