Prompts

The @clack/prompts package provides a collection of pre-built, high-level prompts that make it easy to create interactive command-line interfaces. It builds on top of the core package to provide a more developer-friendly experience.

Key Features

• Pre-built prompts: Ready-to-use prompt components
• Consistent styling: Unified look and feel across all prompts
• Type-safe: Full TypeScript support
• Customizable: Easy to extend and modify

Installation

npm

npm install @clack/prompts

pnpm

pnpm add @clack/prompts

Yarn

yarn add @clack/prompts

Usage

The prompts package is designed to be intuitive and easy to use. Each prompt function returns a Promise that resolves to the user’s input.

For more detailed examples and advanced usage patterns, check out our examples guide and best practices.

Available Prompts

Text Input

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

const name = await text({
  message: 'What is your name?',
  placeholder: 'John Doe',
  validate: (value) => {
    if (value.length < 2) return 'Name must be at least 2 characters';
    return undefined;
  },
});

│
◆  What is your name?
│  John Doe
└

Password Input

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

const secret = await password({
  message: 'What is your password?',
  mask: '*',
  validate: (value) => {
    if (value.length < 8) return 'Your password must be at least 8 characters';
    if (!/[A-Z]/.test(value)) return 'Your password must be least contain 1 uppercase letter';
    if (!/[0-9]/.test(value)) return 'Your password must be least contain 1 number';
    if (!/[*?!@&]/.test(value)) return 'Your password must be least contain 1 special characters (*?!@&)';
    return undefined;
  },
});

│
◆  What is your password?
│  *****_
└

Selection

Simple value

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

const framework = await select({
  message: 'Pick a framework',
  options: [
    { value: 'next', label: 'Next.js', hint: 'React framework' },
    { value: 'astro', label: 'Astro', hint: 'Content-focused' },
    { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' },
  ],
  maxItems: 5, // Maximum number of items to display at once
});

│
◆  Pick a framework
│  ● Next.js (React framework)
│  ○ Astro (Content-focused)
│  ○ SvelteKit (Compile-time framework)
└

Complex value

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

const framework = await select({
  message: 'Pick a framework',
  options: [
    { value: { framework: 'Next', language: 'React' }, label: 'Next.js', hint: 'React framework' },
    { value: { framework: null, language: 'Astro' }, label: 'Astro', hint: 'Content-focused' },
    { value: { framework: 'Sveltekit', language: 'Svelte' }, label: 'SvelteKit', hint: 'Compile-time framework' },
  ],
});

│
│  Pick a framework
│  ● Next.js (React framework)
│  ○ Astro (Content-focused)
│  ○ SvelteKit (Compile-time framework)
└

Multiple values

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

const framework = await multiselect({
  message: 'Pick a framework',
  options: [
    { value: { framework: 'Next', language: 'React' }, label: 'Next.js', hint: 'React framework' },
    { value: { framework: null, language: 'Astro' }, label: 'Astro', hint: 'Content-focused' },
    { value: { framework: 'Sveltekit', language: 'Svelte' }, label: 'SvelteKit', hint: 'Compile-time framework' },
  ],
  maxItems: 5, // Maximum number of items to display at once
});

│
◆  Pick a framework
│  ◼ Next.js (React framework)
│  ◻ Astro (Content-focused)
│  ◻ SvelteKit (Compile-time framework)
└

Autocomplete

The autocomplete prompt combines text input with a searchable list of options. It’s perfect for when you have a large list of options and want to help users find what they’re looking for quickly.

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

const framework = await autocomplete({
  message: 'Search for a framework',
  options: [
    { value: 'next', label: 'Next.js', hint: 'React framework' },
    { value: 'astro', label: 'Astro', hint: 'Content-focused' },
    { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' },
    { value: 'remix', label: 'Remix', hint: 'Full stack framework' },
    { value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' },
  ],
  placeholder: 'Type to search...',
  maxItems: 5, // Maximum number of items to display at once
});

│
◆  Search for a framework
│  Search: n
│  (2 matches)
│  ● Next.js (React framework)
│  ○ Nuxt (Vue framework)
└

Autocomplete Multiselect

The autocompleteMultiselect combines the search functionality of autocomplete with the ability to select multiple options.

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

const frameworks = await autocompleteMultiselect({
  message: 'Select frameworks',
  options: [
    { value: 'next', label: 'Next.js', hint: 'React framework' },
    { value: 'astro', label: 'Astro', hint: 'Content-focused' },
    { value: 'svelte', label: 'SvelteKit', hint: 'Compile-time framework' },
    { value: 'remix', label: 'Remix', hint: 'Full stack framework' },
    { value: 'nuxt', label: 'Nuxt', hint: 'Vue framework' },
  ],
  placeholder: 'Type to search...',
  maxItems: 5, // Maximum number of items to display at once
});

│
◆  Select frameworks
│  Search: n
│  (2 matches)
│  ◼ Next.js (React framework)
│  ◻ Nuxt (Vue framework)
└

Confirmation

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

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

│
◆  Do you want to continue?
│  ● Yes / ○ No
└

Grouping

Group Multiselect

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

const projectOptions = await groupMultiselect({
    message: 'Define your project',
    options: {
        'Testing': [
            { value: 'Jest', hint: 'JavaScript testing framework' },
            { value: 'Playwright', hint: 'End-to-end testing' },
            { value: 'Vitest', hint: 'Vite-native testing' },
        ],
        'Language': [{
            label: "Javascript",
            value: 'js',
            hint: 'Dynamic typing'
        }, {
            label: 'TypeScript',
            value: 'ts',
            hint: 'Static typing'
        }, {
            label: "CoffeeScript",
            value: 'coffee',
            hint: 'JavaScript with Ruby-like syntax'
        }],
        'Code quality': [
            { value: 'Prettier', hint: 'Code formatter' },
            { value: 'ESLint', hint: 'Linter' },
            { value: 'Biome.js', hint: 'Formatter and linter' },
        ],
    },
    groupSpacing: 1, // Add one new line between each group
    selectableGroups: false, // Disable selection of top-level groups
});

│
◆  Define your project
│  ◼ Testing
│  │ ◼ Jest (JavaScript testing framework)
│  │ ◼ Playwright (End-to-end testing)
│  └ ◼ Vitest (Vite-native testing)
│
│  ◻ Language
│  │ ◼ Javascript (Dynamic typing)
│  │ ◻ TypeScript (Static typing)
│  └ ◻ CoffeeScript (JavaScript with Ruby-like syntax)
│
│  ◻ Code quality
│  │ ◻ Prettier (Code formatter)
│  │ ◻ ESLint (Linter)
│  └ ◼ Biome.js (Formatter and linter)
└

The groupMultiselect prompt supports two additional options:

• groupSpacing: An integer that specifies how many new lines to add between each group. This helps improve readability when you have many groups.
• selectableGroups: A boolean that determines whether top-level groups can be selected. When set to false, only individual items within groups can be selected.

Group

The group function provides a convenient API for combining a series of questions. Each question receives the results of previous answers. The group function returns an object containing the result of every question.

import { group, text, password } from '@clack/prompts';

const account = await group({
    email: () => text({
        message: 'What is your email address?',
        validate: (value) => {
            if (!/^[a-z0-9_.-]+@[a-z0-9_.-]+\.[a-z]{2,}$/i.test(value)) return 'Please enter a valid email'
        }
    }),
    username: ({results}) => text({
        message: 'What is your username?',
        placeholder: results.email?.replace(/@.+$/, '').toLowerCase() ?? '',
        validate: (value) => {
            // FOR DEMO PURPOSES ONLY! Use a robust validation library in production
            if (value.length < 2) return 'Please enter at least 2 characters'
        }
    }),
    password: () => password({
        message: 'Define your password'
    }),
});

│
◇  What is your email address?
│  user.name@example.com
│
◇  What is your username?
│  bomb_sh
│
◆  Define your password
│  ▪▪▪▪▪▪▪▪▪▪▪▪_
└

Tasks

The tasks function provides a convenient API for sequencing several asynchronous actions one after the other.

import { tasks } from "@clack/prompts";

await tasks([
    {
        title: 'Downloading package',
        task: async () => {
            // Do a fetch
            return 'Download completed';
        },
    },
    {
        title: "Un-archiving",
        task: async (message) => {
            const parts: Array<string> = [/* ... */];
            for (let index = 0; index < parts.length; index++) {
                const type = parts[index];
                // Update the message to indicate what is done
                message(`Un-archiving ${type} (${index + 1}/${parts.length})`);
                // Do the un-archiving task
            }
            return 'Un-archiving completed';
        },
    },
    {
        title: 'Linking',
        task: async () => {
            // Do work
            return 'Package linked';
        },
    },
]);

│
◇  Download completed
│
◐  Un-archiving lib (2/3)..

Support functions

Intro

The intro function defines the beginning of an interaction. It accepts an optional string parameter which is displayed as a title for the interaction.

Tip

Feel free to use ANSI escape sequences to add colors and a more branded feel to your intro message!

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

intro('Welcome to clack');

┌  Welcome to clack

Outro

The outro function defines the end of an interaction. It accepts an optional string parameter which is displayed as a concluding message.

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

outro('All operations are finished');

│
└  All operations are finished
 

Cancel

The cancel function defines an interruption of an interaction and therefore its end. It accepts an optional string parameter which is displayed as a cancellation message.

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

cancel('Installation canceled');

└  Installation canceled
 

Spinner

The spinner function provides a loading indicator for long-running operations.

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

const spin = spinner();
spin.start('Loading');
// Do something
spin.message('Finishing');
// Do more things
spin.stop('Done');

│
◒  Loading...

You can customize the spinner’s messages either per instance or globally:

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

// Global customization
updateSettings({
  messages: {
    cancel: "Operation cancelled",
    error: "An error occurred",
  },
});

// Per-instance customization
const spin = spinner({
  cancelMessage: "Process cancelled",
  errorMessage: "Process failed",
});

spin.start('Loading');
// Do something
spin.stop('Done');

The second parameter of spinner.stop (code) allow you to indicate the ending status of the spinner:

• 0 (or no value) indicate a success and the symbol for a finished task will be used
• 1 indicate a cancellation and the red square symbol will be used
• Any other code indicate an error and the yellow triangle symbol will be used

You can also use custom frames for the spinner:

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

const spin = spinner({
  frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
});
spin.start('Loading');
// Do something
spin.stop('Done');

Progress

The progress prompt displays a progress bar for long-running operations.

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

const prog = progress();
prog.start('Processing files');
// Update progress
prog.message('Halfway there');
// Update again
prog.message('Complete');
prog.stop('All files processed');

│
◆  Processing files
│  [████████████████████████████████████] 100%
│  Complete
◆  All files processed

Note

The note function renders a box around a message to draw a user’s attention. This is useful for displaying next steps and linking to your documentation towards the end of an interaction.

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

note(
  'You can edit the file src/index.jsx',
  'Next steps.'
);

│
◇  Next steps. ─────────────────────────╮
│                                       │
│  You can edit the file src/index.jsx  │
│                                       │
├───────────────────────────────────────╯

The second parameter (the title) is optional. You can also provide a format function to customize how each line is displayed:

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

note(
  'Line 1\nLine 2\nLine 3',
  'Formatted steps',
  {
    format: (line: string) => `→ ${line}`
  }
);

│
◇  Formatted steps
◇   ─────────────────────────────╮
│                                │
│  → Line 1                      │
│  → Line 2                      │
│  → Line 3                      │
│                                │
├────────────────────────────────╯

Task Log

The taskLog prompt provides a way to display log output that is cleared on success. This is useful for showing progress or status updates that should be removed once the task is complete.

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

const log = taskLog({
  title: 'Installing dependencies'
});
log.message('Fetching package information...');
// Do some work
log.message('Installing packages...');
// Do more work
log.success('Installation complete');

│
◆  Installing dependencies
│  Fetching package information…
│  Installing packages…
◆  Installation complete

Logs

The log utilities allow you to add semantic contextual information during an interaction. Each function renders with specific styling to communicate status.

log is an object containing the following methods:

• log.message displays a message without any symbols to communicate state
• log.info displays a message with a neutral state
• log.warn (alias log.warning) displays a message with a caution state
• log.error displays a message with a danger state
• log.success displays a message with a success state
• log.step displays a message with a neutral, completed state

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

log.message('Entering directory "src"');
log.info('No files to update');
log.warn('Directory is empty, skipping');
log.warning('Directory is empty, skipping');
log.error('Permission denied on file src/secret.js');
log.success('Installation complete');
log.step('Check files');

│
│  Entering directory “src”
│
●  No files to update
│
▲  Directory is empty, skipping
│
▲  Directory is empty, skipping
│
■  Permission denied on file src/secret.js
│
◆  Installation complete
│
◇  Check files

Internationalization

The prompts package supports internationalization through the updateSettings function. You can customize the messages used by various prompts to match your preferred language.

import { updateSettings, select, cancel } from '@clack/prompts';

// Update global messages
updateSettings({
  messages: {
    cancel: "Operación cancelada",
    error: "Se ha producido un error"
  }
});

// Use the select prompt with translated content
const framework = await select({
  message: 'Selecciona un framework',
  options: [
    { value: 'next', label: 'Next.js', hint: 'Framework de React' },
    { value: 'astro', label: 'Astro', hint: 'Enfocado en contenido' },
    { value: 'svelte', label: 'SvelteKit', hint: 'Framework de compilación' },
  ]
});

// If the user cancels, they'll see the translated message
if (!framework) {
  cancel();
}

│
◆  Selecciona un framework
│  ● Next.js (Framework de React)
│  ○ Astro (Enfocado en contenido)
│  ○ SvelteKit (Framework de compilación)
└
└  Operación cancelada
 

Stream

The stream utilities allow you, like the log utilities, to add semantic contextual information during an interaction, expect that the message contains an unknown number of lines. Each function renders with specific styling to communicate status.

Tip

These utilities are useful to print content of node:stream, like file stream

import { stream } from "@clack/prompts";
import * as fs from "node:fs";

await stream.message(fs.createReadStream('./banner.txt', { encoding: 'utf-8' }));
await stream.info((async function*() {
    yield 'Open file...';
    // Open file
    yield ' \x1b[32mOK\x1b[39m\n';

    yield 'Parsing file...';
    // Parse data
    yield ' \x1b[32mOK\x1b[39m';
    return;
})());
await stream.step([
    'Job1...',
    ' \x1b[32mdone\x1b[39m\n',
    'Job2...',
    ' \x1b[32mdone\x1b[39m\n',
    'Job3...',
    ' \x1b[32mdone\x1b[39m',
]);

│
│
│  ⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣶⣶⣿⣿⣿⣿⣿⣿⣶⣶⣤⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
│  ⠀⠀⠀⠀⠀⣠⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
│  ⠀⠀⠀⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
│  ⠀⠀⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
│  ⠀⣼⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧ ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀
│  ⢰⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⣀⠀⠀⠀⠀⣿⣿⣿⡿⠀⠀⠀⠀⣀⠀
│  ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⠀⠀⠀⠀⢠⣿⣿⣶⣤⣄⣻⣿⣿⣇⣠⣴⣶⣿⣿⡀
│  ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⢾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡧
│  ⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠀⠀⠀⠀⠀⠀⠀⠉⢉⣿⣿⣿⣿⣿⣯⡉⠉⠀⠀⠀
│  ⠸⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⢀⣴⣿⣿⣿⠟⢻⣿⣿⣿⣦⠀⠀⠀
│  ⠀⢻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡟⠀⠀⠀⠀⠀⠀⠐⠿⣿⣿⣿⠏⠀⠀⢻⣿⣿⣿⠷⠀⠀
│  ⠀⠀⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠏⠀⠀⠀⠀⠹⠋⠁⠀⠀⠀
│  ⠀⠀⠀⠙⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
│  ⠀⠀⠀⠀⠀⠙⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠟⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
│  ⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠻⠿⢿⣿⣿⣿⣿⡿⠿⠟⠛⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
│
│
●  Open file... OK
│  Parsing file... OK
│
◇  Job1... done
│  Job2... done
│  Job3... done