@cli-prompts/multiline

A modern, flicker-free, feature-rich multiline text input for your command-line applications.

Have you ever been frustrated that inquirer and other great libraries are missing a proper, smooth multiline text input? This package solves that. It's a standalone component designed from the ground up to provide a first-class "textarea" experience in the terminal.

✨ Features

• True Multiline Editing: A native-like textarea experience in the terminal.
• Intuitive Key-bindings: Enter to submit, Shift+Enter for newlines.
• Advanced Editing: Word-wise navigation (Ctrl+Left/Right) and deletion (Alt+Backspace, Ctrl+W).
• Robust Paste Support: Reliably paste multi-line text without accidentally submitting.
• Rich Feature Set: Supports placeholders, default values, validation, and max length.
• Animated Spinners: Optional loading spinner for a dynamic feel.
• Deeply Customizable: Change prefixes, colors, and more with a simple style object.
• Flicker-Free: Built with a smart, atomic render loop.
• Lightweight & Modern: Zero runtime dependencies, written in TypeScript.
• Battle-Tested: High unit test coverage.

📦 Installation

# pnpm
pnpm add @cli-prompts/multiline

# npm
npm install @cli-prompts/multiline

# yarn
yarn add @cli-prompts/multiline

# bun
bun add @cli-prompts/multiline

🚀 Usage

import { multiline, AbortError } from '@cli-prompts/multiline';

async function main() {
  try {
    const description = await multiline({
      prompt: 'Please enter your project description:',
      placeholder: 'My project is about...\nIt does really cool things!',
    });

    console.log('\nYour description:\n ', description);
  } catch (error) {
    if (error instanceof AbortError) {
      // The user aborted the prompt (Ctrl+C).
      // The component already printed a cancellation message.
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

main();

⚙️ API & Options

The multiline function accepts a string for a simple prompt, or an options object for full configuration.

multiline(options: MultilineOptions): Promise<string>

🎨 Styling

You can customize the look and feel by passing a style object. You only need to provide the properties you want to override.

Example:

import chalk from 'chalk';

multiline({
  prompt: 'Enter commit message',
  style: {
    prefixes: {
      prompt: '🤔',
      success: '✅',
    },
    colors: {
      prompt: 'yellow', // Use a predefined color name
      finalAnswer: str => chalk.italic.hex('#888')(str), // Or use a custom function
    },
  },
});

Style Object Structure:

{
  prefixes?: {
    prompt?: string;    // default: '?'
    success?: string;   // default: '✔'
    error?: string;     // default: '✖'
    input?: string;     // default: '›'
  };
  colors?: {
    prompt?: ColorFn | ColorName;      // default: 'cyan'
    success?: ColorFn | ColorName;     // default: 'green'
    error?: ColorFn | ColorName;       // default: 'red'
    instruction?: ColorFn | ColorName; // default: 'gray'
    placeholder?: ColorFn | ColorName; // default: 'gray'
    finalAnswer?: ColorFn | ColorName; // default: 'cyan'
    inputPrefix?: ColorFn | ColorName; // default: 'gray'
    promptTitle?: ColorFn | ColorName; // default: 'bold'
  };
}

ColorName can be one of: 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'gray'. ColorFn is a function (str: string) => string.

⌨️ Key Bindings

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.