Requirements

• Node.js v22 or higher

Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @topcli/prompts
# or
$ yarn add @topcli/prompts

Usage exemple

You can locally run node ./demo.js

import { question, confirm, select, multiselect } from "@topcli/prompts";

const kTestRunner = ["node", "tap", "tape", "vitest", "mocha", "ava"];

const name = await question("Project name ?", { defaultValue: "foo" });
const runner = await select("Choose a test runner", { choices: kTestRunner, maxVisible: 5 });
const isCLI = await confirm("Your project is a CLI ?", { initial: true });
const os = await multiselect("Choose OS", {
  choices: ["linux", "mac", "windows"],
  preSelectedChoices: ["linux"]
});

console.log(name, runner, isCLI, os);

API

question()

question<T = string>(message: string, options?: QuestionOptions<T>): Promise<T>

Simple prompt, similar to rl.question() with an improved UI.

Use options.defaultValue to set a default value.

Use options.hint to display a hint alongside the question.

Use options.secure if you need to hide both input and answer. You can provide either a boolean or an object which allows to configure a placeholder such as *.

Use options.signal to set an AbortSignal (throws a AbortError).

Use options.validators to validate user input and re-prompt on failure.

Use options.transformer to parse and validate user input in a single step, returning a typed value. Mutually exclusive with validators.

Use options.skip to skip prompt. It will return options.defaultValue if given, "" otherwise.

Validators examples

const packageName = await question('Package name', {
  validators: [
    {
      validate: (value) => {
        if (fs.existsSync(path.join(process.cwd(), value))) {
          return `Folder ${value} already exists`;
        }
      }
    }
  ]
});

Validators can also be async, for example to validate against an API:

const userId = await question('User ID', {
  validators: [
    {
      validate: async(userId) => {
        const res = await fetch(`https://api.com/users/${userId}`);
        if (!res.ok) {
          return {
            isValid: false,
            error: `User '${userId}' not found`
          }
        }
      }
    }
  ]
});

Transformers examples

import { question, transformers } from "@topcli/prompts";

const port = await question("Port", { transformer: transformers.number() });

Custom transformer:

const date = await question("Choose date (YYYY-MM-DD)", {
  transformer: {
    transform: (input) => {
      const date = new Date(input);

      if (isNaN(date.getTime())) {
        return { isValid: false, error: "invalid date" };
      }

      return { isValid: true, transformed: date };
    }
  }
});

Built-in validators

• validators.required() : rejects empty input

import { question, validators } from "@topcli/prompts";

const name = await question("What's your name ?", {
  validators: [validators.required()]
});

Built-in transformers

• transformers.number(): parses input as a number, rejects non-numeric and empty strings
• transformers.integer(): parses input as an integer, rejects floats, non-numeric and empty strings
• transformers.url(): parses input as a URL object, rejects invalid URLs

import { question, transformers } from "@topcli/prompts";

const count = await question("Count", { transformer: transformers.integer() });
const url = await question("Url", { transformer: transformers.url() });

select()

select<T extends string>(message: string, options: SelectOptions<T>): Promise<T>

Scrollable select depending maxVisible (default 8).

Use options.ignoreValues to skip result render & clear lines after a selected one.

Use options.validators to handle user input.

Use options.autocomplete to allow filtered choices. This can be useful for a large list of choices.

Use options.caseSensitive to make autocomplete filters case sensitive. Default false

Use options.signal to set an AbortSignal (throws a AbortError).

Use options.skip to skip prompt. It will return the first non-separator choice.

Use Separator items in choices to visually group options. Separators are not selectable and are skipped during keyboard navigation. When autocomplete is active and the user has typed a filter, separators are hidden.

import { select } from "@topcli/prompts";

const framework = await select("Choose a framework", {
  choices: [
    { type: "separator", label: "Frontend" },
    { value: "react", label: "React" },
    { value: "vue", label: "Vue" },
    { type: "separator", label: "Backend" },
    { value: "express", label: "Express" },
    { value: "fastify", label: "Fastify" },
  ]
});

Use choice.disabled to mark a choice as non-selectable.

const runner = await select("Choose a runner", {
  choices: [
    { value: "node", label: "Node.js" },
    { value: "bun", label: "Bun", disabled: "not available" },
    { value: "deno", label: "Deno", disabled: true }
  ]
});

multiselect()

multiselect<T extends string>(message: string, options: MultiselectOptions<T>): Promise<T[]>

Scrollable multiselect depending options.maxVisible (default 8).
Use options.preSelectedChoices to pre-select choices.

Use options.validators to handle user input.

Use options.showHint: false to disable hint (this option is truthy by default).

Use options.autocomplete to allow filtered choices. This can be useful for a large list of choices.

Use options.caseSensitive to make autocomplete filters case sensitive. Default false.

Use options.signal to set an AbortSignal (throws a AbortError).

Use options.skip to skip prompt. It will return options.preSelectedChoices if given, [] otherwise.

Use Separator items in choices to visually group options. Separators are not selectable and are skipped during keyboard navigation. When autocomplete is active and the user has typed a filter, separators are hidden.

Use choice.disabled to mark a choice as non-selectable.

confirm()

confirm(message: string, options?: ConfirmOptions): Promise<boolean>

Boolean prompt, default to options.initial (false).

Tip

You can answer pressing Y or N

Use options.signal to set an AbortSignal (throws a AbortError).

Use options.skip to skip prompt. It will return options.initial (false by default)

PromptAgent

The PromptAgent class allows to programmatically set the next answers for any prompt function, this can be useful for testing.

const agent = PromptAgent.agent();
agent.nextAnswer("John");

const input = await question("What's your name?");
assert.equal(input, "John");

Warning

Answers set with PromptAgent will bypass any logical & validation rules. Examples:

• When using question(), validators functions will not be executed.
• When using select(), the answer can be different from the available choices.
• When using confirm(), the answer can be any type other than boolean.
• etc
  Use with caution

Errors

AbortError

export class AbortError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "AbortError";
  }
}

Interfaces

type Stdin = NodeJS.ReadStream & {
  fd: 0;
};

type Stdout = NodeJS.WriteStream & {
  fd: 1;
}

export interface AbstractPromptOptions {
  stdin?: Stdin;
  stdout?: Stdout;
  message: string;
  skip?: boolean;
  signal?: AbortSignal;
}

export interface PromptValidator<T extends string | string[]> {
  validate: (input: T) => ValidationResponse | Promise<ValidationResponse>;
}

export interface PromptTransformer<T> {
  transform: (input: string) => TransformationResponse<T> | Promise<TransformationResponse<T>>;
}

export type ValidTransformationResponse<T> = {
  isValid: true;
  transformed: T;
};

export type TransformationResponse<T> = InvalidResponse | ValidTransformationResponse<T>;

export interface QuestionOptions<T = string> extends AbstractPromptOptions {
  defaultValue?: string;
  hint?: string;
  validators?: PromptValidator<string>[];
  transformer?: PromptTransformer<T>;
  secure?: boolean | { placeholder: string };
}

export interface Choice<T = any> {
  value: T;
  label: string;
  description?: string;
  disabled?: boolean | string;
}

export interface Separator {
  type: "separator";
  label?: string;
}

export interface SelectOptions<T extends string> extends AbstractPromptOptions {
  choices: (Choice<T> | T | Separator)[];
  maxVisible?: number;
  ignoreValues?: (T | number | boolean)[];
  validators?: PromptValidator<string>[];
  autocomplete?: boolean;
  caseSensitive?: boolean;
}

export interface MultiselectOptions<T extends string> extends AbstractPromptOptions {
  choices: (Choice<T> | T | Separator)[];
  maxVisible?: number;
  preSelectedChoices?: (Choice<T> | T)[];
  validators?: PromptValidator<string[]>[];
  autocomplete?: boolean;
  caseSensitive?: boolean;
  showHint?: boolean;
}

export interface ConfirmOptions extends AbstractPromptOptions {
  initial?: boolean;
}

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Open an issue if you want to provide feedback such as bug reports or enchancements.

Contributors

PierreDemailly 💻 ⚠️	Gentilhomme 👀 💻 📖	Tony Gorez 👀	Yefis 💻 📖	Ben 📖 🚧	Takeshi Kondo 🚧	FredGuiou 💻 ⚠️ 📖
Marcus Reinhardt 💻 ⚠️ 📖	Harper Andrews 📖