API | Contributing | Changelog
flow-modal is a flexible UI library for orchestrating multi‐step experiences in modern web applications. Built with Web Components, flow-modal makes it easy to create guided flows with built‐in state persistence, rich animations, and event-driven interactions.
-
Modular Components:
-
<flow-modal>: A container that manages and orchestrates a sequence of steps. -
<flow-step>: Represents an individual step in the flow. Each step can include modal content and supports customizable animations. -
<flow-badge>: An optional badge component that can display hints, countdowns, or actionable buttons.
-
-
Rich Animation Options:
Support animations such as fade, fly, and zoom effects for showing/hiding modals and badges. -
State Persistence:
Automatically persist flow state (using local, cookie, or in‑memory storage) so users continue where they left off. -
Event‑Driven Architecture:
Listen to events likeflowmodalstarted,flowstepactivated, orflowbadgeclickedto integrate custom behaviors. -
Accessibility & Customization: Designed with ARIA labels and configurable CSS variables so you can seamlessly match your app’s design.
npm install flow-modalInclude the components in your project by importing them from the published package. For example, you might add the following to your HTML:
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>flow-modal Example</title>
<!-- Import the flow-modal components -->
<script type="module" src="path/to/flow-modal.js"></script>
</head>
<body>
<flow-modal>
<flow-step ready timeout-duration="1m" backdrop hide-button-icon="close">
<flow-badge hint-text="Click to open modal" button-icon="bell" button-count-down-format="mm:ss"></flow-badge>
<h2>Welcome to Our Presentation!</h2>
<p>This is the first step of our presentation flow. You have one minute to review this announcement.</p>
</flow-step>
<flow-step ready backdrop>
<flow-badge button-text="Click"></flow-badge>
<h2>Presentation Details</h2>
<p>Thank you for viewing the introduction. This is the second step of the presentation.</p>
</flow-step>
</flow-modal>
</body>
</html>If you prefer not to install via npm or wish to try out flow-modal quickly, you can load the minified version directly from a CDN. Both unpkg and jsDelivr host the built file from our npm package:
-
Using unpkg:
<script type="module" src="https://unpkg.com/flow-modal/dist/index.js"></script>
-
Using jsDelivr:
<script type="module" src="https://cdn.jsdelivr.net/npm/flow-modal/dist/index.js"></script>
Simply include one of these <script> tags in your HTML <head> and start using flow-modal as documented above.
You can also explore the live Storybook on Chromatic for interactive examples and to tweak properties in real time.
See here for the API reference.
flow-modal supports a variety of animations that you can use to customize the appearance and behavior of your components. Use the corresponding attributes (e.g., modal-show-animation, hint-hide-animation) or override the default CSS variables to control the animations.
| Name | Example | Name | Example |
|---|---|---|---|
fade-in |
fade-out |
||
fly-in-from-left |
fly-out-to-left |
||
fly-in-from-right |
fly-out-to-right |
||
fly-in-from-top |
fly-out-to-top |
||
fly-in-from-bottom |
fly-out-to-bottom |
||
zoom-in |
zoom-out |
To ensure a smooth user experience and prevent the flash of unstyled content before the web components have fully loaded, add the following CSS rule to your global stylesheet or inline in the <head> of your HTML document:
flow-step:not(:defined),
flow-modal:not(:defined) {
display: none;
}flow-modal includes a series of Bun tests verifying functionality.
bun testThis project is licensed under the MIT License. See LICENSE for details.