flow-modal v1.1.0
flow-modal 
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.
🌟 Features
- 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.
🚀 Getting Started
Installation
npm install flow-modalBasic Usage
Include 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>Using via CDN
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.
Live Demo
You can also explore the live Storybook on Chromatic for interactive examples and to tweak properties in real time.
🧑💻️ API reference
See here for the API reference.
🎞 Animations
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 |
🐞 Tips
Prevent Flash of Unstyled Content (FOUC)
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;
}💻 Testing
flow-modal includes a series of Bun tests verifying functionality.
bun test💳 License
This project is licensed under the MIT License. See LICENSE for details.