feat: add multi-select mode (#12) (#24)

Space toggles the highlighted item; Enter confirms the full selection via
onConfirm. defaultSelectedKeys pre-populates checked state. onToggle fires
on each individual toggle. Hotkeys are disabled in multi-select mode to
avoid Space ambiguity. DefaultIndicatorComponent renders [x]/[ ] checkboxes
when isChecked is provided. isChecked is threaded through to both custom
indicatorComponent and itemComponent. 13 new tests cover all paths.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: gfargo

readme.md

@@ -17,6 +17,7 @@ An enhanced, customizable select input component for [Ink](https://github.com/va
 - **Keyboard Navigation:** Arrow keys and Vim-like keys (`h/j/k/l`) supported.
 - **Hooks for Highlight & Selection:** Run custom logic on highlight and selection changes.
 - **Limit Displayed Items:** Restrict how many options to show at once.
+- **Multi-select Mode:** Space to toggle, Enter to confirm a multi-item selection.
 
 ## Compatibility
 
@@ -77,6 +78,41 @@ render(<Demo />)
 />
 ```
 
+### Multi-select
+
+Enable multi-select mode with the `multiple` prop. Space toggles an item; Enter confirms the full selection.
+
+```tsx
+import React, { useState } from 'react'
+import { render, Text } from 'ink'
+import { EnhancedSelectInput } from 'ink-enhanced-select-input'
+
+const options = [
+  { label: 'TypeScript', value: 'ts' },
+  { label: 'React', value: 'react' },
+  { label: 'Ink', value: 'ink' },
+  { label: 'Legacy (unsupported)', value: 'legacy', disabled: true },
+]
+
+function MultiDemo() {
+  return (
+    <EnhancedSelectInput
+      items={options}
+      multiple
+      defaultSelectedKeys={['ts']}
+      onToggle={(item, checked) =>
+        console.log(`${item.label} is now ${checked ? 'checked' : 'unchecked'}`)
+      }
+      onConfirm={(selected) =>
+        console.log('Confirmed:', selected.map((i) => i.value))
+      }
+    />
+  )
+}
+
+render(<MultiDemo />)
+```
+
 ### Per-Item Indicators
 
 ```tsx
@@ -144,23 +180,27 @@ function MyCustomSelect({ items, onSelect }) {
 }
 ```
 
-The hook accepts all the same props as `EnhancedSelectInput` except `indicatorComponent`, `itemComponent`, and `showScrollIndicators`. It returns `{ selectedIndex, rotateIndex, visibleItems, hasItems, itemsAbove, itemsBelow }`.
+The hook accepts all the same props as `EnhancedSelectInput` except `indicatorComponent`, `itemComponent`, and `showScrollIndicators`. It returns `{ selectedIndex, rotateIndex, visibleItems, hasItems, itemsAbove, itemsBelow, checkedKeys }`. `checkedKeys` is a `Set<string>` of checked item keys — only populated when `multiple` is `true`.
 
 ## Props
 
-| Prop                 | Type                         | Default                     | Description                              |
-| -------------------- | ---------------------------- | --------------------------- | ---------------------------------------- |
-| `items`              | `Array<Item<V>>`             | _required_                  | List of selectable items                 |
-| `isFocused`          | `boolean`                    | `true`                      | Whether the component responds to input  |
-| `initialIndex`       | `number`                     | `0`                         | Index of the initially highlighted item  |
-| `limit`              | `number`                     | —                           | Max number of visible items              |
-| `indicatorComponent` | `FC<IndicatorProps>`         | `DefaultIndicatorComponent` | Custom selection indicator               |
-| `itemComponent`      | `FC<ItemProps>`              | `DefaultItemComponent`      | Custom item renderer                     |
-| `onSelect`           | `(item: Item<V>) => void`    | —                           | Called on selection (Enter or hotkey)    |
-| `onHighlight`        | `(item: Item<V>) => void`    | —                           | Called when the highlighted item changes |
-| `onCancel`           | `() => void`                 | —                           | Called when Escape is pressed            |
-| `orientation`        | `'vertical' \| 'horizontal'` | `'vertical'`                | Layout direction                         |
-| `showScrollIndicators` | `boolean`                  | `false`                     | Show ▲/▼ or ◀/▶ counts when `limit` clips the list |
+| Prop                   | Type                              | Default                     | Description                              |
+| ---------------------- | --------------------------------- | --------------------------- | ---------------------------------------- |
+| `items`                | `Array<Item<V>>`                  | _required_                  | List of selectable items                 |
+| `isFocused`            | `boolean`                         | `true`                      | Whether the component responds to input  |
+| `initialIndex`         | `number`                          | `0`                         | Index of the initially highlighted item  |
+| `limit`                | `number`                          | —                           | Max number of visible items              |
+| `indicatorComponent`   | `FC<IndicatorProps>`              | `DefaultIndicatorComponent` | Custom selection indicator               |
+| `itemComponent`        | `FC<ItemProps>`                   | `DefaultItemComponent`      | Custom item renderer                     |
+| `onSelect`             | `(item: Item<V>) => void`         | —                           | Called on selection (Enter or hotkey) — single-select only |
+| `onHighlight`          | `(item: Item<V>) => void`         | —                           | Called when the highlighted item changes |
+| `onCancel`             | `() => void`                      | —                           | Called when Escape is pressed            |
+| `orientation`          | `'vertical' \| 'horizontal'`      | `'vertical'`                | Layout direction                         |
+| `showScrollIndicators` | `boolean`                         | `false`                     | Show ▲/▼ or ◀/▶ counts when `limit` clips the list |
+| `multiple`             | `boolean`                         | `false`                     | Enable multi-select mode (Space toggles, Enter confirms) |
+| `defaultSelectedKeys`  | `string[]`                        | —                           | Pre-checked item keys for multi-select   |
+| `onConfirm`            | `(items: Array<Item<V>>) => void` | —                           | Called on Enter in multi-select mode with all checked items |
+| `onToggle`             | `(item: Item<V>, checked: boolean) => void` | —             | Called each time an item is toggled in multi-select mode |
 
 ### Item Shape
 
@@ -183,12 +223,14 @@ type Item<V> = {
 
 ## Keyboard Navigation
 
-| Orientation | Previous  | Next      | First    | Last    | Select  | Cancel   |
-| ----------- | --------- | --------- | -------- | ------- | ------- | -------- |
-| Vertical    | `↑` / `k` | `↓` / `j` | `Home`   | `End`   | `Enter` | `Escape` |
-| Horizontal  | `←` / `h` | `→` / `l` | `Home`   | `End`   | `Enter` | `Escape` |
+| Orientation | Previous  | Next      | First    | Last    | Select / Confirm | Toggle (multi) | Cancel   |
+| ----------- | --------- | --------- | -------- | ------- | ---------------- | -------------- | -------- |
+| Vertical    | `↑` / `k` | `↓` / `j` | `Home`   | `End`   | `Enter`          | `Space`        | `Escape` |
+| Horizontal  | `←` / `h` | `→` / `l` | `Home`   | `End`   | `Enter`          | `Space`        | `Escape` |
+
+In **single-select** mode, `Enter` calls `onSelect` and hotkeys select immediately. In **multi-select** mode (`multiple={true}`), `Space` toggles the highlighted item and `Enter` calls `onConfirm` with all checked items. Hotkeys are disabled in multi-select mode to avoid ambiguity with `Space`.
 
-Hotkeys (when assigned) select the item immediately. Disabled items are automatically skipped during navigation, including by `Home` and `End`.
+Disabled items are automatically skipped during navigation, including by `Home` and `End`.
 
 `Escape` calls the `onCancel` prop when provided — useful for multi-step CLI flows that need a "go back" action.
 

src/enhanced-select-input/index.tsx

@@ -26,6 +26,23 @@ export type UseEnhancedSelectInputProperties<V> = {
   /** Called when Escape is pressed while the component is focused. */
   readonly onCancel?: () => void
   readonly orientation?: 'vertical' | 'horizontal'
+  /** Enable multi-select mode. Space toggles, Enter confirms. */
+  readonly multiple?: boolean
+  /**
+   * Pre-selected item keys in multi-select mode.
+   * Each entry should match an item's `key` field (or `String(value)` fallback).
+   */
+  readonly defaultSelectedKeys?: string[]
+  /**
+   * Called when the user confirms a multi-select (Enter).
+   * Only used when `multiple` is true.
+   */
+  readonly onConfirm?: (items: Array<Item<V>>) => void
+  /**
+   * Called each time an item is toggled in multi-select mode (Space).
+   * Receives the toggled item and whether it is now checked.
+   */
+  readonly onToggle?: (item: Item<V>, checked: boolean) => void
 }
 
 /** Full component props — hook props plus rendering customisation. */
@@ -42,6 +59,8 @@ export type Properties<V> = UseEnhancedSelectInputProperties<V> & {
 
 export type IndicatorProperties = {
   readonly isSelected: boolean
+  /** True when the item is checked in multi-select mode. Undefined in single-select mode. */
+  readonly isChecked?: boolean
   // eslint-disable-next-line  react/no-unused-prop-types
   readonly item: Item<unknown>
 }
@@ -50,6 +69,8 @@ export type ItemProperties = {
   readonly isSelected: boolean
   readonly label: string
   readonly isDisabled: boolean
+  /** True when the item is checked in multi-select mode. Undefined in single-select mode. */
+  readonly isChecked?: boolean
 }
 
 // Vim navigation keys that take precedence over hotkeys.
@@ -109,6 +130,10 @@ export function findLastValidIndex<V>(items: Array<Item<V>>): number {
   return items.length - 1
 }
 
+function itemKey<V>(item: Item<V>): string {
+  return item.key ?? String(item.value)
+}
+
 export type UseEnhancedSelectInputResult<V> = {
   /** Index of the currently highlighted item within the full items array. */
   selectedIndex: number
@@ -122,6 +147,8 @@ export type UseEnhancedSelectInputResult<V> = {
   itemsAbove: number
   /** Number of items hidden below the current window. */
   itemsBelow: number
+  /** Keys of checked items. Only populated in multi-select mode. */
+  checkedKeys: Set<string>
 }
 
 /**
@@ -138,12 +165,19 @@ export function useEnhancedSelectInput<V>({
   onHighlight,
   onCancel,
   orientation = 'vertical',
+  multiple = false,
+  defaultSelectedKeys,
+  onConfirm,
+  onToggle,
 }: UseEnhancedSelectInputProperties<V>): UseEnhancedSelectInputResult<V> {
   const safeInitialIndex = resolveInitialIndex(items, initialIndex)
   const [selectedIndex, setSelectedIndex] = useState(safeInitialIndex)
   const [rotateIndex, setRotateIndex] = useState(
     limit ? Math.floor(safeInitialIndex / limit) * limit : 0
   )
+  const [checkedKeys, setCheckedKeys] = useState<Set<string>>(
+    () => new Set(defaultSelectedKeys ?? [])
+  )
 
   const hasItems = items.length > 0
   const visibleItems = limit
@@ -161,7 +195,7 @@ export function useEnhancedSelectInput<V>({
   // String(value) to produce "[object Object]" for every item.
   useEffect(() => {
     if (process.env['NODE_ENV'] !== 'production' && items.length > 0) {
-      const keys = items.map((item) => item.key ?? String(item.value))
+      const keys = items.map((item) => itemKey(item))
       const seen = new Set<string>()
       const duplicates = new Set<string>()
       for (const k of keys) {
@@ -230,6 +264,24 @@ export function useEnhancedSelectInput<V>({
         return
       }
 
+      // Space: toggle in multi-select mode
+      if (multiple && input === ' ') {
+        const item = items[selectedIndex]
+        if (item && !item.disabled) {
+          const k = itemKey(item)
+          setCheckedKeys((prev) => {
+            const next = new Set(prev)
+            const nowChecked = !next.has(k)
+            if (nowChecked) next.add(k)
+            else next.delete(k)
+            onToggle?.(item, nowChecked)
+            return next
+          })
+        }
+
+        return
+      }
+
       let nextIndex = selectedIndex
 
       if (orientation === 'vertical') {
@@ -255,15 +307,21 @@ export function useEnhancedSelectInput<V>({
       }
 
       if (key.return) {
-        const selectedItem = items[selectedIndex]
-        if (selectedItem && !selectedItem.disabled) {
-          onSelect?.(selectedItem)
+        if (multiple) {
+          // In multi-select mode Enter confirms the full selection
+          const confirmed = items.filter((item) => checkedKeys.has(itemKey(item)))
+          onConfirm?.(confirmed)
+        } else {
+          const selectedItem = items[selectedIndex]
+          if (selectedItem && !selectedItem.disabled) {
+            onSelect?.(selectedItem)
+          }
         }
       }
 
       // Hotkeys: nav keys for the active orientation take priority.
-      // See README "Keyboard Navigation" for reserved key constraints.
-      if (!isNavKey) {
+      // Hotkeys are not active in multi-select mode to avoid ambiguity.
+      if (!multiple && !isNavKey) {
         const hotkeyItem = items.find(
           (item) => item.hotkey === input && !item.disabled
         )
@@ -277,10 +335,33 @@ export function useEnhancedSelectInput<V>({
     { isActive: isFocused }
   )
 
-  return { selectedIndex, rotateIndex, visibleItems, hasItems, itemsAbove, itemsBelow }
+  return {
+    selectedIndex,
+    rotateIndex,
+    visibleItems,
+    hasItems,
+    itemsAbove,
+    itemsBelow,
+    checkedKeys,
+  }
 }
 
-export function DefaultIndicatorComponent({ isSelected }: IndicatorProperties) {
+export function DefaultIndicatorComponent({
+  isSelected,
+  isChecked,
+}: IndicatorProperties) {
+  if (isChecked !== undefined) {
+    // Multi-select mode: show checkbox + cursor
+    return (
+      <Box marginRight={1}>
+        <Text color={isSelected ? 'green' : undefined}>
+          {isChecked ? '[x]' : '[ ]'}
+        </Text>
+      </Box>
+    )
+  }
+
+  // Single-select mode: classic arrow cursor
   return (
     <Box marginRight={1}>
       <Text color={isSelected ? 'green' : undefined}>
@@ -312,8 +393,15 @@ export function EnhancedSelectInput<V>({
   // All remaining props are forwarded to the hook
   ...hookProps
 }: Properties<V>) {
-  const { selectedIndex, rotateIndex, visibleItems, hasItems, itemsAbove, itemsBelow } =
-    useEnhancedSelectInput(hookProps)
+  const {
+    selectedIndex,
+    rotateIndex,
+    visibleItems,
+    hasItems,
+    itemsAbove,
+    itemsBelow,
+    checkedKeys,
+  } = useEnhancedSelectInput(hookProps)
 
   if (!hasItems) {
     return <Box />
@@ -322,6 +410,7 @@ export function EnhancedSelectInput<V>({
   const IndicatorComponent = indicatorComponent
   const ItemComponent = itemComponent
   const isVertical = hookProps.orientation !== 'horizontal'
+  const isMultiple = hookProps.multiple === true
 
   return (
     <Box flexDirection={isVertical ? 'column' : 'row'}>
@@ -338,22 +427,30 @@ export function EnhancedSelectInput<V>({
       >
         {visibleItems.map((item, index) => {
           const isSelected = index + rotateIndex === selectedIndex
+          const isChecked = isMultiple
+            ? checkedKeys.has(item.key ?? String(item.value))
+            : undefined
 
           return (
             <Box key={item.key ?? String(item.value)}>
-              {item.indicator ? (
+              {item.indicator && !isMultiple ? (
                 <Box marginRight={1}>
                   <Text>{isSelected ? item.indicator : ' '}</Text>
                 </Box>
               ) : (
-                <IndicatorComponent isSelected={isSelected} item={item} />
+                <IndicatorComponent
+                  isSelected={isSelected}
+                  isChecked={isChecked}
+                  item={item}
+                />
               )}
               <ItemComponent
                 isSelected={isSelected}
                 label={item.label}
                 isDisabled={Boolean(item.disabled)}
+                isChecked={isChecked}
               />
-              {item.hotkey && (
+              {item.hotkey && !isMultiple && (
                 <Text dimColor color="gray">
                   {' '}
                   ({item.hotkey})