@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>

| Option | Type | Default | Description | | ------------- | -------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------- | | prompt | string | Required | The main question to ask the user. | | default | string | '' | A default value to pre-populate the input with. Supports \n for newlines. | | placeholder | string | undefined | Placeholder text to show when the input is empty. Supports \n for newlines. | | instruction | string \| boolean | true | A help message shown below the input. Set to false to hide, or a string to override. | | required | boolean | false | If true, prevents submission if the input is empty or only whitespace. | | validate | (value: string) => boolean \| string | undefined | A function to validate the input on submission. Return true if valid, or a string for an error message. | | maxLength | number | undefined | The maximum number of characters allowed. Provides real-time feedback. | | spinner | boolean | false | If true, replaces the ? prefix with an animated spinner. | | style | object | {...} | An object to customize prefixes and colors. See "Styling" section below. |

🎨 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

| Key | Action | | ----------------------------------- | ---------------------- | | Enter | Submit the input | | Shift + Enter / Alt + Enter | Insert a new line | | Ctrl + C | Abort the prompt | | Backspace | Delete character left | | Delete | Delete character right | | Alt + Backspace | Delete word left | | Ctrl + W | Delete word left | | Arrow Keys | Move cursor | | Ctrl + Left | Move to previous word | | Ctrl + Right | Move to next word |

📄 License

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