inquirerjs-checkbox-search


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

!Demo showing inquirerjs-checkbox-search in action

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

$3

``typescript
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

$3

| Property | Type | Required | Description |
| -------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| message | string | Yes | The question to ask |
| choices | Array | No\* | Static list of choices |
| source | (term?: string, opt: { signal: AbortSignal }) => Promise> | 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) => boolean \| string \| Promise | No | Custom validation function |
| instructions | string \| boolean | No | Custom instructions text or false to hide |
| theme | Theme | No | Custom theme configuration |
| default | Array | No | Initially selected values |
| filter | (items: Array, term: string) => Array | No | Custom filter function |

\*Either choices or source must be provided.

$3

`typescript
type Choice = {
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
};
`

$3

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

`typescript
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

$3

`typescript
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.

$3

#### 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

$3

#### Setup & Installation

`bash


Clone and install


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

#### Development Commands

`bash


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

`bash
npm test
`

2. Before Publishing
`bash
npm run prepublishOnly
`

#### Build & Release Workflow

1. Development Build

`bash
npm run build
npm run dev
`

2. Package Validation

`bash
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.