xonecas.io
6615
Yc

yoctoselect / files

yoctoselect / README.md

1.9 KB
1# yoctoselect
2
3Minimal interactive select prompt for the terminal. Prefix-match filtering, keyboard navigation, inline rendering. Zero bloat.
4
5## Install
6
7```sh
8bun add yoctoselect
9```
10
11## Usage
12
13```ts
14import { select } from "yoctoselect";
15
16const picked = await select({
17  items: ["apple", "banana", "cherry"],
18});
19console.log(picked); // "banana" or null if cancelled
20```
21
22### Rich items
23
24```ts
25import * as c from "yoctocolors";
26
27const model = await select({
28  items: [
29    {
30      label: `claude-sonnet-4  ${c.green("free")}  ${c.dim("200k")}`,
31      value: "anthropic/claude-sonnet-4",
32      filterText: "claude-sonnet-4",
33    },
34    {
35      label: `gpt-4o  ${c.dim("128k")}`,
36      value: "openai/gpt-4o",
37      filterText: "gpt-4o",
38    },
39  ],
40  placeholder: "search models...",
41});
42```
43
44## API
45
46### `select(options): Promise<string | null>`
47
48| Option        | Type           | Default               | Description                |
49| ------------- | -------------- | --------------------- | -------------------------- |
50| `items`       | `SelectItem[]` | required              | Items to select from       |
51| `placeholder` | `string`       | `"type to filter..."` | Shown when search is empty |
52| `maxVisible`  | `number`       | `20`                  | Max items shown at once    |
53
54### `SelectItem`
55
56```ts
57type SelectItem =
58  | string
59  | {
60      label: string; // displayed text (can include ANSI colors)
61      value: string; // returned on selection
62      filterText?: string; // matched against search (defaults to label)
63    };
64```
65
66### Keyboard
67
68| Key            | Action                        |
69| -------------- | ----------------------------- |
70| Type           | Filter items by prefix        |
71| `↑` / `↓`      | Move highlight (wraps around) |
72| `Enter`        | Select highlighted item       |
73| `Escape`       | Cancel, return `null`         |
74| `Home` / `End` | Jump to first/last            |
75| `Backspace`    | Delete last character         |
76
77## License
78
79MIT