A multi-select prompt with text filtering for inquirer.js
npm install 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
- npm: npm install inquirerjs-checkbox-search
- yarn: yarn add inquirerjs-checkbox-search
- pnpm: pnpm add inquirerjs-checkbox-search
``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']
`
| 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 | 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 | No | Custom filter function |
\*Either choices or source must be provided.
`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
};
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)autoBufferDescriptions
2. Calculate buffer:
- If is true: Add lines needed for largest descriptionbuffer
- Add value (if specified)minBuffer
- Ensure buffer is at least (if specified)min
3. Subtract buffer from base page size
4. Apply /max constraints
5. Ensure final result is at least 1
`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
};
| Key | Action |
| ------------------------- | ---------------------------------- |
| Type | Filter/search options |
| ā/ā | Navigate through options |
| Tab | Toggle selection of current option |
| Escape | Clear search filter |
| Enter | Confirm selection |
For detailed examples of advanced features, see the examples/ directory.
Each example includes detailed comments and demonstrates real-world usage patterns.
This section covers the tools and workflows used in this project for contributors and maintainers.
#### Build System
- tshy - Modern TypeScript build tool that generates both ESM and CommonJS outputs
- Configuration in package.json under tshy fielddist/esm/
- Builds to 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.prettierrc
- Rules: TypeScript ESLint recommended + Prettier integration
- Prettier - Code formatting
- Configuration: tsconfig.json
- TypeScript - Type checking and compilation
- Configuration: , 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
#### Setup & Installation
`bash`Clone and install
git clone https://github.com/texarkanine/inquirerjs-checkbox-search.git
cd inquirerjs-checkbox-search
npm install
#### Development Commands
`bashDevelopment (watch mode)
npm run dev # Build in watch mode with tshy
#### 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` branchSee CONTRIBUTING.md for development setup and contribution guidelines.