or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

choice-prompts.mdconfirmation-prompts.mdcore-prompting.mdindex.mdnumber-date-prompts.mdtesting.mdtext-prompts.md
tile.json

tessl/npm-prompts

Lightweight, beautiful and user-friendly interactive CLI prompts library with promise-based API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/prompts@2.4.x

To install, run

npx @tessl/cli install tessl/npm-prompts@2.4.0

index.mddocs/

Prompts

Prompts is a lightweight, beautiful and user-friendly interactive CLI prompts library with promise-based API and async/await support. It provides a comprehensive set of prompt types for gathering user input in command-line applications, with beautiful styling, flexible validation, and consistent experience across all prompt types.

Package Information

  • Package Name: prompts
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install prompts
  • Node Support: >= 6

Core Imports

const prompts = require('prompts');

For ES modules:

import prompts from 'prompts';

Import specific functions:

const { prompt, inject, override } = require('prompts');

Basic Usage

const prompts = require('prompts');

// Single prompt
const response = await prompts({
  type: 'text',
  name: 'username',
  message: 'What is your GitHub username?'
});
console.log(response.username);

// Multiple prompts
const response = await prompts([
  {
    type: 'text',
    name: 'username',
    message: 'What is your GitHub username?'
  },
  {
    type: 'number',
    name: 'age',
    message: 'How old are you?'
  },
  {
    type: 'confirm',
    name: 'subscribe',
    message: 'Would you like to subscribe to our newsletter?'
  }
]);

console.log(response); // { username: 'alice', age: 25, subscribe: true }

Architecture

Prompts is built around several key components:

  • Main Prompt Function: Core prompting function that handles question flow, validation, and response collection
  • Prompt Types: Eleven different prompt types for various input scenarios (text, number, select, etc.)
  • Element Classes: Individual prompt implementation classes that handle rendering and user interaction
  • Testing Utilities: Functions for programmatic response injection and pre-answering questions
  • Utility Modules: Helper functions for styling, formatting, and terminal interaction

Capabilities

Core Prompting

Main prompting functionality for single or multiple questions with promise-based API, validation, and callback support.

function prompts(
  questions: Question | Question[],
  options?: PromptOptions
): Promise<Answers>;

interface Question {
  type: string | ((prev: any, values: Answers, prompt: Question) => string | null);
  name: string | ((prev: any, values: Answers, prompt: Question) => string);
  message: string | ((prev: any, values: Answers, prompt: Question) => string);
  initial?: any | ((prev: any, values: Answers, prompt: Question) => any);
  format?: (val: any, values: Answers) => any;
  validate?: (val: any, values: Answers) => boolean | string;
  onRender?: (kleur: any) => void;
  onState?: (state: { value: any; aborted: boolean }) => void;
  stdin?: NodeJS.ReadableStream;
  stdout?: NodeJS.WritableStream;
}

interface PromptOptions {
  onSubmit?: (prompt: Question, answer: any, answers: Answers) => boolean | Promise<boolean>;
  onCancel?: (prompt: Question, answers: Answers) => boolean | Promise<boolean>;
}

type Answers = Record<string, any>;

Core Prompting

Text Input Prompts

Text-based input prompts including standard text, password (masked), and invisible input modes.

// Text prompt
{
  type: 'text',
  name: 'value',
  message: string,
  initial?: string,
  style?: 'default' | 'password' | 'invisible' | 'emoji',
  validate?: (value: string) => boolean | string,
  format?: (value: string) => any
}

// Password prompt (masked input)
{
  type: 'password',
  name: 'value', 
  message: string,
  initial?: string
}

// Invisible prompt (like sudo)
{
  type: 'invisible',
  name: 'value',
  message: string,
  initial?: string
}

Text Input Prompts

Number and Date Prompts

Numeric and temporal input prompts with validation, increment/decrement controls, and locale support.

// Number prompt
{
  type: 'number',
  name: 'value',
  message: string,
  initial?: number,
  max?: number,
  min?: number,
  float?: boolean,
  round?: number,
  increment?: number,
  style?: 'default' | 'password' | 'invisible' | 'emoji'
}

// Date prompt
{
  type: 'date',
  name: 'value',
  message: string,
  initial?: Date,
  locales?: DateLocales,
  mask?: string,
  validate?: (date: Date) => boolean | string
}

Number and Date Prompts

Choice Selection Prompts

Interactive selection prompts for single choice, multiple choice, and searchable selection from predefined options.

// Single selection
{
  type: 'select',
  name: 'value',
  message: string,
  choices: Choice[],
  initial?: number,
  hint?: string,
  warn?: string
}

// Multiple selection
{
  type: 'multiselect',
  name: 'value',
  message: string,
  choices: Choice[],
  max?: number,
  min?: number,
  hint?: string,
  warn?: string,
  instructions?: string | boolean,
  optionsPerPage?: number
}

// Autocomplete selection
{
  type: 'autocomplete',
  name: 'value',
  message: string,
  choices: Choice[],
  suggest?: (input: string, choices: Choice[]) => Promise<Choice[]>,
  limit?: number,
  style?: string,
  initial?: string | number,
  clearFirst?: boolean,
  fallback?: string
}

interface Choice {
  title: string;
  value?: any;
  description?: string;
  disabled?: boolean;
  selected?: boolean;  // for multiselect only
}

Choice Selection Prompts

Confirmation and Toggle Prompts

Binary choice prompts for yes/no confirmations and toggle switches with custom labels.

// Confirmation prompt
{
  type: 'confirm',
  name: 'value',
  message: string,
  initial?: boolean
}

// Toggle prompt
{
  type: 'toggle',
  name: 'value',
  message: string, 
  initial?: boolean,
  active?: string,
  inactive?: string
}

// List prompt
{
  type: 'list',
  name: 'value',
  message: string,
  initial?: string,
  separator?: string
}

Confirmation and Toggle Prompts

Testing Utilities

Functions for programmatic testing, response injection, and pre-answering questions during automated testing scenarios.

function inject(answers: any[]): void;
function override(answers: Record<string, any>): void;

Testing Utilities

Common Properties

All prompt types support these common properties:

  • type: Prompt type identifier or function returning type
  • name: Property name for the response object or function returning name
  • message: Display message for the user or function returning message
  • initial: Default/initial value or function returning initial value
  • format: Custom formatter function for user input
  • validate: Input validation function returning true or error message
  • onState: State change callback with current state object
  • onRender: Render callback with kleur styling library access
  • stdin: Input stream (defaults to process.stdin)
  • stdout: Output stream (defaults to process.stdout)

Dynamic properties can be functions with signature (prev, values, prompt) => value where:

  • prev: Value from the previous prompt
  • values: All collected responses so far
  • prompt: Previous prompt object

Error Handling

Prompts can be canceled by users with Esc, Ctrl+C, or Ctrl+D. When canceled, the promise resolves with partial answers collected so far. Use the onCancel callback to handle cancellation events.

The validate function should return true for valid input or an error message string for invalid input. If false is returned, a default error message is shown.