https://github.com/yujiosaka/flow-modal
A guided, multi-step modal using customizable web components and state persistence.
https://github.com/yujiosaka/flow-modal
component flow lit modal webcomponent
Last synced: 6 months ago
JSON representation
A guided, multi-step modal using customizable web components and state persistence.
- Host: GitHub
- URL: https://github.com/yujiosaka/flow-modal
- Owner: yujiosaka
- License: mit
- Created: 2024-12-30T06:24:21.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-02-02T17:50:39.000Z (8 months ago)
- Last Synced: 2025-03-27T18:18:25.857Z (7 months ago)
- Topics: component, flow, lit, modal, webcomponent
- Language: TypeScript
- Homepage:
- Size: 721 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Funding: docs/FUNDING.yml
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
# flow-modal [](https://badge.fury.io/js/flow-modal) [](https://github.com/yujiosaka/flow-modal/actions/workflows/ci_cd.yml)
###### [API](https://github.com/yujiosaka/flow-modal/blob/main/docs/API.md) | [Contributing](https://github.com/yujiosaka/flow-modal/blob/main/docs/CONTRIBUTING.md) | [Changelog](https://github.com/yujiosaka/flow-modal/blob/main/docs/CHANGELOG.md)
**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:**
- ``: A container that manages and orchestrates a sequence of steps.
- ``: Represents an individual step in the flow. Each step can include modal content and supports customizable animations.
- ``: 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 like `flowmodalstarted`, `flowstepactivated`, or `flowbadgeclicked` to 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
```bash
npm install flow-modal
```
### Basic Usage
Include the components in your project by importing them from the published package. For example, you might add the following to your HTML:
```html
flow-modal Example
Welcome to Our Presentation!
This is the first step of our presentation flow. You have one minute to review this announcement.
Presentation Details
Thank you for viewing the introduction. This is the second step of the presentation.
```
### 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:**
```html
```
- **Using jsDelivr:**
```html
```
Simply include one of these `` tags in your HTML `<head>` and start using flow-modal as documented above.
### Live Demo
You can also explore the live [Storybook on Chromatic](https://main--67987fa0e37e8d240be96359.chromatic.com/) for interactive examples and to tweak properties in real time.
## 🧑💻️ API reference
See [here](https://github.com/yujiosaka/flow-modal/blob/main/docs/API.md) 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:
```css
flow-step:not(:defined),
flow-modal:not(:defined) {
display: none;
}
```
## 💻 Testing
flow-modal includes a series of [Bun](https://bun.sh/) tests verifying functionality.
```bash
bun test
```
## 💳 License
This project is licensed under the MIT License. See [LICENSE](https://github.com/yujiosaka/flow-modal/blob/main/LICENSE) for details.