tinky-multi-select

A flexible and interactive multi-select component for building command-line interfaces (CLIs) with Tinky.

Features

• ✅ Multi-selection: Select multiple items from a list using Space.
• ⌨️ Keyboard Navigation: Navigate through options using Arrow keys.
• 📜 Scrolling: efficient rendering for long lists with configurable visible window.
• 🎨 Theming Support: Fully customizable appearance using tinky-theme.
• 🧩 Headless Mode: Exports hooks (useMultiSelect, useMultiSelectState) for building custom UI implementations with the same logic.
• 🔍 Filtering Support: Built-in support for highlighting matched text (filtering logic to be implemented by consumer).

Installation

npm install tinky-multi-select
# or
bun add tinky-multi-select
# or
yarn add tinky-multi-select

Basic Usage

import React, { useState } from "react";
import { render, Text, Box } from "tinky";
import { MultiSelect, type Option } from "tinky-multi-select";

const options: Option[] = [
  { label: "Apple", value: "apple" },
  { label: "Banana", value: "banana" },
  { label: "Cherry", value: "cherry" },
  { label: "Date", value: "date" },
  { label: "Elderberry", value: "elderberry" },
];

function App() {
  const [selected, setSelected] = useState<string[]>([]);
  const [submitted, setSubmitted] = useState(false);

  if (submitted) {
    return <Text color="green">You selected: {selected.join(", ")}</Text>;
  }

  return (
    <Box flexDirection="column">
      <Text>Please select your favorite fruits:</Text>
      <Box marginY={1}>
        <MultiSelect
          options={options}
          onChange={setSelected}
          onSubmit={() => setSubmitted(true)}
        />
      </Box>
      <Text color="gray">
        (Press <Text color="bold">Space</Text> to select,{" "}
        <Text color="bold">Enter</Text> to submit)
      </Text>
    </Box>
  );
}

render(<App />);

Keyboard Controls

| Key | Action | | --------- | -------------------------------------- | | ↑ / ↓ | Navigate through the options | | Space | Toggle selection of the focused option | | Enter | Submit the selection |

API Reference

<MultiSelect />

The main component for rendering the multi-select list.

| Prop | Type | Default | Description | | -------------------- | --------------------------- | ------------ | --------------------------------------------------------------------------------------- | | options | Option[] | Required | Array of data objects to display as options. | | defaultValue | string[] | [] | Array of values that should be selected initially. | | visibleOptionCount | number | 5 | functionality number of items to show at once. Enables scrolling for larger lists. | | isDisabled | boolean | false | If true, the component will not respond to user input. | | highlightText | string | undefined | Substring to highlight within option labels. Useful when implementing search/filtering. | | onChange | (value: string[]) => void | undefined | Callback fired whenever the selection changes. | | onSubmit | (value: string[]) => void | undefined | Callback fired when the user presses Enter. |

Option Interface

interface Option {
  label: string; // Text to display
  value: string; // Unique identifier
}

Headless Usage (Advanced)

If you need complete control over the rendering but want to re-use the interaction logic, you can use the exported hooks.

useMultiSelectState

Manages the internal state of the selection (cursor position, selected items, scrolling).

import { useMultiSelectState } from "tinky-multi-select";

const state = useMultiSelectState({
  options,
  defaultValue: ["apple"],
  visibleOptionCount: 5,
});

// state.visibleOptions -> options currently in view
// state.focusedValue -> value of the currently highlighted option
// state.value -> array of selected values

useMultiSelect

Connects the state to Tinky's input handling system.

import { useMultiSelect } from "tinky-multi-select";

useMultiSelect({
  state, // return value from useMultiSelectState
  isDisabled: false,
});

Theming

This component uses tinky-theme for styling. You can customize the appearance by providing a theme to your ThemeProvider matching the MULTI_SELECT_COMPONENT_NAME.

The styles object structure:

• container: File-level box style
• option: Style for individual option row
• label: Style for the option text
• focusIndicator: Style for the cursor/pointer
• selectedIndicator: Style for the checkmark
• highlightedText: Style for matched text in filter mode

License

MIT