xonecas.io
6615
Yc

yoctoselect / commit 0a70766

docs: README with API docs and usage examples

xonecas2026-03-21 0a7076662f90d4912f266eedac42deeeb99e0376 parent bdf82e9

1 file changed

README.md+79−0
@@ -0,0 +1,79 @@
1+# yoctoselect
2+
3+Minimal interactive select prompt for the terminal. Prefix-match filtering, keyboard navigation, inline rendering. Zero bloat.
4+
5+## Install
6+
7+```sh
8+bun add yoctoselect
9+```
10+
11+## Usage
12+
13+```ts
14+import { select } from "yoctoselect";
15+
16+const picked = await select({
17+ items: ["apple", "banana", "cherry"],
18+});
19+console.log(picked); // "banana" or null if cancelled
20+```
21+
22+### Rich items
23+
24+```ts
25+import * as c from "yoctocolors";
26+
27+const 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
57+type 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+
79+MIT