# 🖥️ React Command Flow
A beautifully interactive CLI-style command interface for React apps.
Type commands, flow through steps, and build dynamic, conversational UI experiences.
---
## ✨ Features
- 🖋 Terminal-style input & output
- 📋 Step-based command flows
- ✅ Built-in validation (sync & async)
- 🔀 Conditional prompts, branching logic
- ⚡ Dynamic suggestions & tab completion
- 💅 Theme support
- 🔍 Help & clear commands out of the box
- 🔌 Easy to extend and customize
---
## 📦 Installation
```bash
npm install react-command-flow
```
---
## ⚡ Usage
```jsx
import React from "react";
import { CommandLine } from "react-command-flow";
import { commands } from "./commands";
export default function App() {
return (
React Command Flow Demo
);
}
```
---
## 📚 Defining Commands
```js
const colors = ["Red", "Green", "Blue", "Yellow", "Purple"];
const shapes = ["Circle", "Square", "Triangle", "Rectangle", "Hexagon"];
const commands = {
"color-shape-quiz": {
description: "Start your color and shape quiz 🌈🔺",
steps: [
{
prompt: async () => {
await new Promise((res) => setTimeout(res, 1000)); // async wait
return `What is your favorite color?\n${colors
.map((c, i) => `${i + 1}. ${c}`)
.join("\n")}\nEnter color index:`;
},
field: "colorIndex",
validate: async (val) => {
return ["1", "2", "3", "4", "5"].includes(val)
? true
: "❌ Please select a number between 1 and 5.";
},
redirect: (val) => {
const color = colors[parseInt(val) - 1];
if (color === "Red") return "color-red-flow";
if (color === "Green") return "color-green-flow";
if (color === "Blue") return "color-blue-flow";
if (color === "Yellow") return "color-yellow-flow";
if (color === "Purple") return "color-purple-flow";
return "color-other-flow";
},
},
],
onComplete: () => "Redirecting...",
},
"color-red-flow": {
description: "Red color path 🔴",
hidden: true,
steps: [
{
prompt: "What shape do you associate with Red?",
field: "redShape",
validate: (val) => {
return shapes.includes(val) ? true : "❌ Please enter a valid shape.";
},
},
],
onComplete: async () => {
await new Promise((res) => setTimeout(res, 1000)); // fake async post
return "✅ Red is a powerful color!";
},
},
"color-green-flow": {
description: "Green color path 🟢",
hidden: true,
steps: [
{
prompt: "What shape do you associate with Green?",
field: "greenShape",
validate: (val) => {
return shapes.includes(val) ? true : "❌ Please enter a valid shape.";
},
},
],
onComplete: async () => {
await new Promise((res) => setTimeout(res, 1000)); // fake async post
return "✅ Green is a calming color!";
},
},
"color-blue-flow": {
description: "Blue color path 🔵",
hidden: true,
steps: [
{
prompt: "What shape do you associate with Blue?",
field: "blueShape",
validate: (val) => {
return shapes.includes(val) ? true : "❌ Please enter a valid shape.";
},
},
],
onComplete: async () => {
await new Promise((res) => setTimeout(res, 1000)); // fake async post
return "✅ Blue is a soothing color!";
},
},
"color-yellow-flow": {
description: "Yellow color path 🟡",
hidden: true,
steps: [
{
prompt: "What shape do you associate with Yellow?",
field: "yellowShape",
validate: (val) => {
return shapes.includes(val) ? true : "❌ Please enter a valid shape.";
},
},
{
prompt: "What emotion do you associate with Yellow?",
field: "yellowEmotion",
validate: (val) => {
const emotions = ["happiness", "energy", "warmth", "caution"];
return emotions.includes(val.toLowerCase())
? true
: "❌ Please enter a valid emotion (happiness, energy, warmth, caution).";
},
},
{
prompt: "What object do you associate with Yellow?",
field: "yellowObject",
validate: (val) => {
return val.length > 0 ? true : "❌ Please enter a valid object.";
},
},
],
onComplete: async () => {
await new Promise((res) => setTimeout(res, 1000)); // fake async post
return "✅ Yellow is a bright and cheerful color!";
},
},
"color-purple-flow": {
description: "Purple color path 🟣",
hidden: true,
steps: [
{
prompt: "What shape do you associate with Purple?",
field: "purpleShape",
validate: (val) => {
return shapes.includes(val) ? true : "❌ Please enter a valid shape.";
},
},
],
onComplete: async () => {
await new Promise((res) => setTimeout(res, 1000)); // fake async post
return "✅ Purple is a royal color!";
},
},
"color-other-flow": {
description: "Other color path 🌈",
hidden: true,
steps: [],
onComplete: () => "💛 All colors are beautiful!",
},
help: {
description: "List available commands",
steps: [],
onComplete: (_, __, all) => {
return Object.entries(all)
.filter(([_, c]) => !c.hidden)
.map(([name, c]) => `- ${name}: ${c.description}`)
.join("\n");
},
},
clear: {
description: "Clear the screen",
steps: [],
onComplete: () => "__CLEAR__",
},
};
// Alias added outside
commands["?"] = commands.help;
export default commands;
```
---
## 🧠 Advanced Examples
- 🔁 Async prompt resolution
- ✅ Custom validation per step
- 🔀 `onStep` logic to transform values
- 🧭 Conditional steps (based on previous answers)
- 📦 Redirects to subcommands (optional)
- 🔄 Repeat functionality with custom repeat questions
### 🎯 Repeat Configuration
Commands can use a comprehensive `repeat` object for full control over the repeat behavior:
```js
const commands = {
"job-application": {
description: "Job application flow",
steps: [
/* ... */
],
onComplete: (data) => `Application submitted for ${data.name}`,
repeat: {
mode: "ask",
question: "💼 Submit another application ({{yes}},{{no}})?",
yes: "sure",
no: "nope",
wrongInput: "Please select either {{yes}} or {{no}}:",
yesReply: "Starting new application...",
noReply: "Application process completed.",
targetCommand: "other-command", // Optional: redirect to different command
},
},
survey: {
description: "User survey",
steps: [
/* ... */
],
onComplete: (data) => "Survey completed!",
repeat: {
mode: "ask",
// Function-based custom repeat question
question: ({ yesOption, noOption, commandName }) =>
`🔄 Take the survey again? Type '${yesOption}' to continue or '${noOption}' to finish.`,
yes: "y",
no: "n",
wrongInput: "Please select either {{yes}} or {{no}}:",
yesReply: "Let's do another survey!",
noReply: "Thanks for participating!",
},
},
"async-demo": {
description: "Async repeat question demo",
steps: [
/* ... */
],
onComplete: (data) => "Task completed!",
repeat: {
mode: "ask",
// Async function-based custom repeat question
question: async ({ yesOption, noOption, commandName }) => {
// Simulate async operation (e.g., checking user preferences)
await new Promise((resolve) => setTimeout(resolve, 500));
return `🤔 Continue with another task? Type '${yesOption}' or '${noOption}'.`;
},
yes: "y",
no: "n",
wrongInput: "Please select either {{yes}} or {{no}}:",
yesReply: "Great! Let's continue...",
noReply: "Task session ended.",
},
},
};
```
**Repeat Object Properties:**
- `mode` - "yes", "no", or "ask"
- `question` - Custom repeat question (string or function)
- `yes` - Custom "yes" option text
- `no` - Custom "no" option text
- `wrongInput` - Custom error message for invalid input
- `yesReply` - Custom message when user selects "yes"
- `noReply` - Custom message when user selects "no"
- `targetCommand` - Optional: different command to run on repeat
**Available placeholders for string-based questions and messages:**
- `{{yes}}` - The "yes" option value
- `{{no}}` - The "no" option value
- `{command}` - The command name (legacy format)
**Function parameters for dynamic questions:**
- `yesOption` - The "yes" option string
- `noOption` - The "no" option string
- `commandName` - The name of the command
---
## 🖌️ Theming
Supports custom themes with colors and fonts.
You can pass a `theme` prop to ``.
---
## 💡 Example Commands You Can Try
- `hello`
- `profile-setup`
- `select-server`
- `help`
- `clear`
---
## 📜 License
MIT — free to use, modify, contribute.
Made with 💛 by Stam & React Command Flow Contributors.
---
## ⭐ Star this repo if you like it!
Let's build the coolest CLI UIs in the React world 🌍