Skip to main content

​
Overview

The Select widget displays a list of options that users can navigate with arrow keys and select. It’s useful for menus, dropdowns, and any UI that requires choosing from a list.

​
Constructor

const select = new Select(options?: SelectOptions);

​
SelectOptions

​
options
string[]
Initial list of options to display. Can be modified later using addOption(), removeOption(), and clearOptions().
​
width
string | number
Width of the select widget. Accepts:
  • Number: fixed width in cells
  • String: percentage (e.g., "50%") or "auto"
​
height
string | number
Height of the select widget. Accepts:
  • Number: fixed height in rows
  • String: percentage (e.g., "100%") or "auto"
​
fg
string | number
Foreground (text) color. Accepts:
  • Hex string: "#FF0000"
  • Color name: "red", "blue", etc.
  • 256-color code: 196
​
bg
string | number
Background color. Same format as fg.
​
border
string
Border style. Valid values:
  • "none" - no border
  • "single" - single-line border
  • "double" - double-line border
  • "rounded" - rounded corners
  • "bold" - bold border

​
Methods

​
addOption()

Add an option to the end of the list. 
addOption(text: string): void
​
text
string
The option text to add.
Source: ts/src/widgets/select.ts:34

​
removeOption()

Remove an option by index. 
removeOption(index: number): void
​
index
number
Zero-based index of the option to remove. Does nothing if index is out of range.
Source: ts/src/widgets/select.ts:42

​
clearOptions()

Remove all options from the list. 
clearOptions(): void
Source: ts/src/widgets/select.ts:46

​
getOptionCount()

Get the total number of options. 
getOptionCount(): number
​
return
number
The number of options in the list.
Source: ts/src/widgets/select.ts:50

​
getOption()

Get the text of a specific option. 
getOption(index: number): string
​
index
number
Zero-based index of the option to retrieve.
​
return
string
The option text at the specified index.
Note: Options are limited to 256 bytes (UTF-8 encoded). Longer strings will be truncated. Source: ts/src/widgets/select.ts:56

​
setSelected()

Set the currently selected option. 
setSelected(index: number): void
​
index
number
Zero-based index of the option to select. Will be clamped to valid range.
Source: ts/src/widgets/select.ts:63

​
getSelected()

Get the currently selected option index. 
getSelected(): number
​
return
number
Zero-based index of the selected option. Returns -1 if no options exist.
Source: ts/src/widgets/select.ts:67

​
Examples

import { Select } from "kraken-tui";

const select = new Select({
  options: ["Option 1", "Option 2", "Option 3"],
  width: 30,
  height: 10,
  border: "single",
});

// Get selected index
const selected = select.getSelected();
console.log(`Selected: ${select.getOption(selected)}`);

​
Inherited Methods

Select inherits all methods from the Widget base class, including:
  • setVisible(visible) - Control visibility
  • setForeground(color) - Set text color
  • setBackground(color) - Set background color
  • setBorderStyle(style) - Change border style
  • destroy() - Clean up resources
See the Widget API reference for the complete list.

​
Event Handling

Select widgets respond to keyboard events:
  • Up/Down arrows - Navigate between options
  • Page Up/Down - Jump multiple options
  • Home/End - Jump to first/last option
  • Enter - Confirm selection (application handles this)
Listen for events using app.drainEvents() in your event loop.

​
Notes

  • Selection is automatically clamped to valid range [0, optionCount-1]
  • Selected option is visually highlighted (styling depends on theme)
  • Options have a 256-byte limit (UTF-8 encoded) due to fixed buffer size
  • Use arrow keys for navigation; the selected index updates automatically
  • For dropdown-style menus, combine with visibility controls
  • Select widgets cannot have children

Build docs developers (and LLMs) love

Get started for freeTalk to us