@clack/prompts

What is @clack/prompts?

@clack/prompts is an npm package designed to facilitate the creation of interactive command-line prompts. It provides a variety of prompt types to gather user input in a streamlined and user-friendly manner.

What are @clack/prompts's main functionalities?

Text Prompt

This feature allows you to prompt the user for a text input. The example code asks the user for their name and then greets them.

const { text } = require('@clack/prompts');

(async () => {
  const name = await text({
    message: 'What is your name?'
  });
  console.log(`Hello, ${name}!`);
})();

Select Prompt

This feature allows you to present a list of options for the user to select from. The example code asks the user to choose a color from a list of options.

const { select } = require('@clack/prompts');

(async () => {
  const color = await select({
    message: 'Choose a color',
    choices: [
      { title: 'Red', value: 'red' },
      { title: 'Green', value: 'green' },
      { title: 'Blue', value: 'blue' }
    ]
  });
  console.log(`You chose ${color}.`);
})();

Confirm Prompt

This feature allows you to ask the user a yes/no question. The example code asks the user if they want to continue and logs a message based on their response.

const { confirm } = require('@clack/prompts');

(async () => {
  const proceed = await confirm({
    message: 'Do you want to continue?'
  });
  console.log(proceed ? 'Continuing...' : 'Operation aborted.');
})();

Password Prompt

This feature allows you to securely prompt the user for a password. The example code asks the user to enter their password and logs a confirmation message.

const { password } = require('@clack/prompts');

(async () => {
  const secret = await password({
    message: 'Enter your password:'
  });
  console.log('Password received.');
})();

Other packages similar to @clack/prompts

inquirer

Inquirer.js is a popular library for creating interactive command-line interfaces. It offers a wide range of prompt types and is highly customizable. Compared to @clack/prompts, Inquirer.js has a larger community and more extensive documentation.

prompts

Prompts is a lightweight, beautiful, and user-friendly library for creating command-line prompts. It supports various prompt types and is known for its simplicity and ease of use. While @clack/prompts focuses on a streamlined API, Prompts offers more customization options.

enquirer

Enquirer is a powerful and flexible library for creating interactive command-line prompts. It supports a wide range of prompt types and offers advanced features like validation and conditional prompts. Enquirer is more feature-rich compared to @clack/prompts, but it may have a steeper learning curve.

README

@clack/prompts

Effortlessly build beautiful command-line apps 🪄 Try the demo

@clack/prompts is an opinionated, pre-styled wrapper around @clack/core.

• 🤏 80% smaller than other options
• 💎 Beautiful, minimal UI
• ✅ Simple API
• 🧱 Comes with text, confirm, select, multiselect, and spinner components

Basics

Setup

The intro and outro functions will print a message to begin or end a prompt session, respectively.

import { intro, outro } from '@clack/prompts';

intro(`create-my-app`);
// Do stuff
outro(`You're all set!`);

Cancellation

The isCancel function is a guard that detects when a user cancels a question with CTRL + C. You should handle this situation for each prompt, optionally providing a nice cancellation message with the cancel utility.

import { isCancel, cancel, text } from '@clack/prompts';

const value = await text({
  message: 'What is the meaning of life?',
});

if (isCancel(value)) {
  cancel('Operation cancelled.');
  process.exit(0);
}

Components

Text

The text component accepts a single line of text.

import { text } from '@clack/prompts';

const meaning = await text({
  message: 'What is the meaning of life?',
  placeholder: 'Not sure',
  initialValue: '42',
  validate(value) {
    if (value.length === 0) return `Value is required!`;
  },
});

Confirm

The confirm component accepts a yes or no answer. The result is a boolean value of true or false.

import { confirm } from '@clack/prompts';

const shouldContinue = await confirm({
  message: 'Do you want to continue?',
});

Select

The select component allows a user to choose one value from a list of options. The result is the value prop of a given option.

import { select } from '@clack/prompts';

const projectType = await select({
  message: 'Pick a project type.',
  options: [
    { value: 'ts', label: 'TypeScript' },
    { value: 'js', label: 'JavaScript' },
    { value: 'coffee', label: 'CoffeeScript', hint: 'oh no' },
  ],
});

Multi-Select

The multiselect component allows a user to choose many values from a list of options. The result is an array with all selected value props.

import { multiselect } from '@clack/prompts';

const additionalTools = await multiselect({
  message: 'Select additional tools.',
  options: [
    { value: 'eslint', label: 'ESLint', hint: 'recommended' },
    { value: 'prettier', label: 'Prettier' },
    { value: 'gh-action', label: 'GitHub Action' },
  ],
  required: false,
});

Spinner

The spinner component surfaces a pending action, such as a long-running download or dependency installation.

import { spinner } from '@clack/prompts';

const s = spinner();
s.start('Installing via npm');
// Do installation here
s.stop('Installed via npm');

Utilities

Grouping

Grouping prompts together is a great way to keep your code organized. This accepts a JSON object with a name that can be used to reference the group later. The second argument is an optional but has a onCancel callback that will be called if the user cancels one of the prompts in the group.

import * as p from '@clack/prompts';

const group = await p.group(
  {
    name: () => p.text({ message: 'What is your name?' }),
    age: () => p.text({ message: 'What is your age?' }),
    color: ({ results }) =>
      p.multiselect({
        message: `What is your favorite color ${results.name}?`,
        options: [
          { value: 'red', label: 'Red' },
          { value: 'green', label: 'Green' },
          { value: 'blue', label: 'Blue' },
        ],
      }),
  },
  {
    // On Cancel callback that wraps the group
    // So if the user cancels one of the prompts in the group this function will be called
    onCancel: ({ results }) => {
      p.cancel('Operation cancelled.');
      process.exit(0);
    },
  }
);

console.log(group.name, group.age, group.color);

Tasks

Execute multiple tasks in spinners.

await p.tasks([
  {
    title: 'Installing via npm',
    task: async (message) => {
      // Do installation here
      return 'Installed via npm';
    },
  },
]);

Logs

import { log } from '@clack/prompts';

log.info('Info!');
log.success('Success!');
log.step('Step!');
log.warn('Warn!');
log.error('Error!');
log.message('Hello, World', { symbol: color.cyan('~') });

Stream

When interacting with dynamic LLMs or other streaming message providers, use the stream APIs to log messages from an iterable, even an async one.

import { stream } from '@clack/prompts';

stream.info((function *() { yield 'Info!'; })());
stream.success((function *() { yield 'Success!'; })());
stream.step((function *() { yield 'Step!'; })());
stream.warn((function *() { yield 'Warn!'; })());
stream.error((function *() { yield 'Error!'; })());
stream.message((function *() { yield 'Hello'; yield ", World" })(), { symbol: color.cyan('~') });