Core

The @clack/core package provides the fundamental building blocks for creating interactive command-line interfaces. It’s designed to be flexible, extensible, and easy to use.

Key Features

• Low-level primitives: Base components for building custom prompts
• Type-safe: Built with TypeScript for better developer experience
• Flexible rendering: Customizable rendering system for prompts
• Cancel handling: Built-in support for handling user cancellation
• Event system: Comprehensive event handling for user interactions
• Input validation: Built-in support for input validation
• Abort signal support: Integration with AbortController for cancellation
• Custom I/O streams: Support for custom input/output streams
• Configurable guide lines: Toggle the default Clack border with withGuide

Installation

To start using the core package, first install it:

npm

npm install @clack/core

pnpm

pnpm add @clack/core

Yarn

yarn add @clack/core

Then import the components you need:

import {
  // Prompt classes
  TextPrompt,
  SelectPrompt,
  ConfirmPrompt,
  PasswordPrompt,
  MultiSelectPrompt,
  GroupMultiSelectPrompt,
  SelectKeyPrompt,
  AutocompletePrompt,

  // Utilities
  isCancel,
  updateSettings,
  settings,

  // Types
  type ClackSettings,
  type PromptOptions,
  type ConfirmOptions,
  type PasswordOptions,
  type MultiSelectOptions,
  type GroupMultiSelectOptions,
  type SelectKeyOptions,
  type AutocompleteOptions,
} from '@clack/core';

The package exports both the prompt classes and their corresponding options types (e.g., ConfirmOptions, PasswordOptions) for TypeScript users.

Package Structure

The core package is organized into two main directories:

• prompts/: Contains the base prompt implementations
• utils/: Contains utility functions and helpers

Core Components

Base Prompt Class

The Prompt class serves as the foundation for all prompt types. It provides:

• Custom rendering capabilities
• Input handling
• State management
• Event system
• Validation support
• Abort signal integration

Key Methods

interface Prompt {
  // Event handling
  on<T extends string>(event: T, cb: (value: any) => void): void;
  once<T extends string>(event: T, cb: (value: any) => void): void;
  emit<T extends string>(event: T, ...data: any[]): void;

  // Core functionality
  prompt(): Promise<string | symbol>;
  close(): void;
}

Available Events

The Prompt interface provides several events that can be handled:

import { Prompt } from '@clack/core';

// Example usage
const p = new Prompt({
  render: () => 'Enter your name:'
});

// Handle value changes
p.on('value', (value?: string) => {
  console.log('Value changed:', value);
});

// Handle submission
p.on('submit', (value?: string) => {
  console.log('Submitted:', value);
});

// Handle cancellation
p.on('cancel', () => {
  console.log('Operation cancelled');
});

Available Prompts

1. TextPrompt: For text input

   • Supports validation
   • Placeholder text
   • Initial value
   • Separate userInput and value tracking

2. SelectPrompt: For selection from options

   • Custom rendering
   • Option filtering
   • Disabled options support
   • Text wrapping support

3. ConfirmPrompt: For yes/no confirmations

   • Yes/No shortcuts
   • Custom messages

4. AutocompletePrompt: For searchable selection

   • Type-ahead filtering
   • Custom filtering logic
   • Multiple selection support (multiple: true)
   • Dynamic options (function or array)

5. PasswordPrompt: For secure input

   • Character masking
   • Validation support
   • clearOnError option to reset on validation failure

6. MultiSelectPrompt: For multiple selections

   • Checkbox interface
   • Selection limits
   • Custom rendering
   • Disabled options support
   • Invert selection support

7. GroupMultiSelectPrompt: For grouped selections

   • Hierarchical options
   • Group selection (selectableGroups option)
   • Custom rendering
   • Group spacing control

8. SelectKeyPrompt: For key-based selection

   • Custom key bindings
   • Multiple selection support

Global Settings

The core package provides global settings that affect all prompts:

import { updateSettings, settings } from '@clack/core';

// Update global settings
updateSettings({
  // Custom key aliases for navigation
  aliases: {
    w: 'up',
    a: 'left',
    s: 'down',
    d: 'right',
  },
  // Disable guide lines globally
  withGuide: false,
  // Custom messages for i18n
  messages: {
    cancel: 'Operación cancelada',
    error: 'Se produjo un error',
  },
});

// Access current settings
console.log(settings.messages.cancel);

Key Aliases

Default keybindings include Vim-style navigation:

Key	Action
k	up
j	down
h	left
l	right
Escape	cancel

You can add custom aliases but cannot disable the default keybindings.

Guide Lines

The withGuide setting controls the display of Clack’s signature border lines. Set to false to render prompts without the decorative guide.

Creating Custom Prompts

You can create custom prompts by extending the base Prompt class:

import { Prompt } from '@clack/core';

// Example of extending the base Prompt class
class CustomPrompt extends Prompt<string> {
  constructor(options: { message: string }) {
    super({
      ...options,
      render() {
        return `${options.message}\n${this.value ?? ''}`;
      }
    });
  }
}

For detailed examples and usage patterns, check out our examples guide.