inquirerjs-checkbox-search

A multi-select prompt with text filtering/search capability for inquirer.js.

This prompt combines the functionality of @inquirer/checkbox and @inquirer/search, allowing you to:

• ✅ Multi-select multiple options with checkboxes
• 🔍 Search/filter options in real-time as you type
• ⌨️ Navigate with arrow keys through filtered results

Installation

• npm: npm install inquirerjs-checkbox-search
• yarn: yarn add inquirerjs-checkbox-search
• pnpm: pnpm add inquirerjs-checkbox-search

Usage

Quick Start

import checkboxSearch from 'inquirerjs-checkbox-search';

const selected = await checkboxSearch({
  message: 'Which frameworks do you use?',
  choices: [
    { value: 'react', name: 'React' },
    { value: 'vue', name: 'Vue.js' },
    { value: 'angular', name: 'Angular' },
  ],
});

console.log('Selected:', selected);
// => ['react', 'vue']

API

Options

| Property | Type | Required | Description | | -------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | message | string | Yes | The question to ask | | choices | Array<Choice \| string \| Separator> | No* | Static list of choices | | source | (term?: string, opt: { signal: AbortSignal }) => Promise<Array<Choice \| string>> | No* | Async function for dynamic choices | | pageSize | number \| PageSizeConfig | No | Page size configuration. Can be a number (fixed size) or PageSizeConfig object for advanced control. If not specified, auto-sizes based on terminal height (fallback: 7) | | loop | boolean | No | Whether to loop around when navigating (default: true) | | required | boolean | No | Require at least one selection (default: false) | | validate | (selection: Array<Choice>) => boolean \| string \| Promise<string \| boolean> | No | Custom validation function | | instructions | string \| boolean | No | Custom instructions text or false to hide | | theme | Theme | No | Custom theme configuration | | default | Array<Value> | No | Initially selected values | | filter | (items: Array<Choice>, term: string) => Array<Choice> | No | Custom filter function |

*Either choices or source must be provided.

Choice Object

type Choice<Value = any> = {
  value: Value; // The value returned when selected
  name?: string; // Display text (defaults to value)
  description?: string; // Additional description shown below
  short?: string; // Shorter text for final answer
  disabled?: boolean | string; // Whether choice is selectable
  checked?: boolean; // Initially selected
};

PageSize Configuration

The pageSize property accepts either a number (for simple fixed sizing) or a PageSizeConfig object for advanced control:

type PageSizeConfig = {
  base?: number; // Starting page size (if not specified, auto-calculated from terminal)
  max?: number; // Maximum page size (absolute constraint)
  min?: number; // Minimum page size (absolute constraint, defaults to 1)
  buffer?: number; // Fixed buffer lines to subtract from page size
  autoBufferDescriptions?: boolean; // Auto-reserve space for descriptions
  autoBufferCountsLineWidth?: boolean; // Consider terminal width when counting description lines
  minBuffer?: number; // Minimum buffer lines (applied after auto/manual buffer)
};

Buffer Calculation Process:

1. Start with base page size (from base or auto-calculated)
2. Calculate buffer:
   • If autoBufferDescriptions is true: Add lines needed for largest description
   • Add buffer value (if specified)
   • Ensure buffer is at least minBuffer (if specified)
3. Subtract buffer from base page size
4. Apply min/max constraints
5. Ensure final result is at least 1

Theme Options

type CheckboxSearchTheme = {
  icon: {
    checked: string | ((text: string) => string); // Icon for checked items
    unchecked: string | ((text: string) => string); // Icon for unchecked items
    cursor: string | ((text: string) => string); // Icon for cursor/current item
    nocursor?: string; // Icon/space placeholder for cursor
  };
  style: {
    message: (text: string) => string; // Style for prompt message
    error: (text: string) => string; // Style for error messages
    help: (text: string) => string; // Style for help text
    highlight: (text: string) => string; // Style for highlighted items (takes precedence)
    searchTerm: (text: string) => string; // Style for search term display
    description: (text: string) => string; // Style for item descriptions
    disabled: (text: string) => string; // Style for disabled items
    checked: (text: string) => string; // Style for checked items
  };
  helpMode: 'always' | 'never' | 'auto'; // When to show help text
};

Keyboard Controls

| Key | Action | | ------------------------- | ---------------------------------- | | Type | Filter/search options | | ↑/↓ | Navigate through options | | Tab | Toggle selection of current option | | Escape | Clear search filter | | Enter | Confirm selection |

Advanced Features

For detailed examples of advanced features, see the examples/ directory.

Each example includes detailed comments and demonstrates real-world usage patterns.

Developer Guide

This section covers the tools and workflows used in this project for contributors and maintainers.

Tools Overview

Build System

• tshy - Modern TypeScript build tool that generates both ESM and CommonJS outputs
  • Configuration in package.json under tshy field
  • Builds to dist/esm/ and dist/commonjs/
  • Automatically handles dual exports

Package Management

• npm - Package manager (npm 9+ required)
• Node.js 20+ - Runtime requirement
• package.json - Standard npm configuration with dual exports

Code Quality

• ESLint - Linting with TypeScript support
  • Configuration: eslint.config.js
  • Rules: TypeScript ESLint recommended + Prettier integration
• Prettier - Code formatting
  • Configuration: .prettierrc
• TypeScript - Type checking and compilation
  • Configuration: tsconfig.json, tsconfig.test.json

Testing

• Vitest - Fast testing framework
  • Configuration: vitest.config.ts
  • Features: TypeScript support, coverage, UI mode, watch mode
• @inquirer/testing - Testing utilities for inquirer prompts
• @vitest/coverage-v8 - Coverage reporting

Development Tools

• @arethetypeswrong/cli - Package validation for dual exports
• rimraf - Cross-platform file deletion

Development Workflows

Setup & Installation

# Clone and install
git clone https://github.com/texarkanine/inquirerjs-checkbox-search.git
cd inquirerjs-checkbox-search
npm install

Development Commands

# Development (watch mode)
npm run dev                # Build in watch mode with tshy

# Building
npm run build             # Build for production
npm run clean             # Clean build artifacts

# Code Quality
npm run lint              # Run ESLint (with --fix)
npm run format            # Format code with Prettier
npm run typecheck         # TypeScript type checking

# Testing
npm test                  # Run all code quality checks + tests
npm run test:unit         # Run unit tests only
npm run test:coverage     # Run tests with coverage report
npm run test:ui           # Run tests with Vitest UI
npm run test:unit -- --watch   # Run tests in watch mode

# Package Validation
npm run attw              # Validate package exports with arethetypeswrong

# Pre-publish
npm run prepublishOnly    # Full build + test + validation pipeline

File Structure

├── src/            # actual source code
│   ├── index.ts
│   └── __tests__/
├── dist/           # build output
│   ├── esm/
│   └── commonjs/
├── examples/       # usage examples
├── demos/          # scripts to record GIFs from examples
├── docs/           # documentation resources
│   └── img/
└── scripts/        # build and utility scripts

Demo Generation

Demo GIFs are automatically generated in CI for PRs and releases: The vhs tool is used to record the examples and save them to GIFs in docs/img/

To generate demos locally, run npm run demo:generate:all (requires docker).

Quality Assurance Workflow

1. Before Committing

   npm test

2. Before Publishing

   npm run prepublishOnly

Build & Release Workflow

1. Development Build

   npm run build
   npm run dev

2. Package Validation

   npm run attw

3. Release Process (Automated)

   • Push changes to main branch
   • Release Please creates/updates release PR
     • demo images are generated and added to the PR
   • Merge release PR to trigger:
     • GitHub release creation
     • npm package publication
     • Version tag creation

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.