`@inquirer/core`

The @inquirer/core package is the library enabling the creation of Inquirer prompts.

It aims to implements a lightweight API similar to React hooks - but without JSX.

Installation

npm install @inquirer/core

yarn add @inquirer/core

Usage

import chalk from 'chalk';
import {
  createPrompt,
  useState,
  useKeypress,
  isEnterKey,
  usePrefix,
} from '@inquirer/core';

const confirm = createPrompt<boolean, { message: string; default?: boolean }>(
  (config, done) => {
    const [status, setStatus] = useState('pending');
    const [value, setValue] = useState('');
    const prefix = usePrefix();

    useKeypress((key, rl) => {
      if (isEnterKey(key)) {
        const answer = value ? /^y(es)?/i.test(value) : config.default !== false;
        setValue(answer ? 'yes' : 'no');
        setStatus('done');
        done(answer);
      } else {
        setValue(rl.line);
      }
    });

    let formattedValue = value;
    let defaultValue = '';
    if (status === 'done') {
      formattedValue = chalk.cyan(value);
    } else {
      defaultValue = chalk.dim(config.default === false ? ' (y/N)' : ' (Y/n)');
    }

    const message = chalk.bold(config.message);
    return `${prefix} ${message}${defaultValue} ${formattedValue}`;
  }
);

/**
 *  Which then can be used like this:
 */
const answer = await confirm({ message: 'Do you want to continue?' });

See more examples:

API

`createPrompt(viewFn)`

The createPrompt function returns an asynchronous function that returns a promise resolving to the valid answer a user submit. This prompt function takes the prompt configuration as its first argument (this is defined by each prompt), and the context options as a second argument.

The prompt configuration is unique to each prompt. The context options are:

Property	Type	Required	Description
input	`NodeJS.ReadableStream`	no	The stdin stream (defaults to `process.stdin`)
output	`NodeJS.WritableStream`	no	The stdout stream (defaults to `process.stdout`)
clearPromptOnDone	`boolean`	no	If true, we'll clear the screen after the prompt is answered

Typescript

If using typescript, createPrompt takes 2 generic arguments (ex createPrompt<string, { message: string }>())

The first one is the type of the resolved value; function createPrompt<Value>(): Promise<Value> {}

The second one is the type of the prompt config; in other words the interface the created prompt will provide to users.

Hooks

Hooks can only be called within the prompt function and are used to handle state and events.

Those hooks are matching the React hooks API:

useState
useRef
useEffect

And those are custom utilities from Inquirer:

useKeypress
usePrefix

Key utilities

Listening for keypress events inside an inquirer prompt is a very common pattern. To ease this, we export a few utility functions taking in the keypress event object and return a boolean:

isEnterKey()
isBackspaceKey()
isSpaceKey()
isUpKey() - Note: this utility will handle vim and emacs keybindings (up, k, and ctrl+p)
isDownKey() - Note: this utility will handle vim and emacs keybindings (down, j, and ctrl+n)
isNumberKey() one of 1, 2, 3, 4, 5, 6, 7, 8, 9, 0

`Paginator`

When looping through a long list of options (like in the select prompt), paginating the results appearing on the screen at once can be necessary. The Paginator utility is there to help this use case.

export default createPrompt((config, done) => {
  const paginator = useRef(new Paginator()).current;

  const windowedChoices = paginator.paginate(allChoices, cursorPosition, config.pageSize);

  return '...';
});

JSPM

@inquirer/core

Package Exports

Readme