Skip to content

Specialized Inputs

@termuijs/ui extends the base TextInput with four purpose-built input components for common terminal UI patterns.

PasswordInput

A text input that masks characters with *. Alt+V toggles visibility.

·CODE
import { PasswordInput } from '@termuijs/ui'

function LoginForm() {
    return (
        <PasswordInput
            placeholder="Password"
            onSubmit={(value) => authenticate(value)}
        />
    )
}
PropTypeDefaultDescription
placeholderstring''Hint text shown when empty
maskstring'*'Replacement character for hidden input
onSubmit(value: string) => void-Called when the user presses Enter
onChange(value: string) => void-Called on every keystroke

Keyboard shortcuts:

  • Alt+V, toggle password visibility (show/hide)
  • Enter, submit
  • Escape, clear input

NumberInput

Restricts input to digits and decimal points. Arrow keys increment/decrement by step.

·CODE
import { NumberInput } from '@termuijs/ui'

function PortField() {
    return (
        <NumberInput
            value={8080}
            min={1}
            max={65535}
            step={1}
            onChange={(n) => setPort(n)}
        />
    )
}
PropTypeDefaultDescription
valuenumber0Initial value
minnumber-InfinityMinimum value, rejects - key when min ≥ 0
maxnumberInfinityMaximum value
stepnumber1Amount to increment/decrement with arrow keys
decimalsnumber0Decimal places to allow
onChange(value: number) => void-Called whenever the value changes
onSubmit(value: number) => void-Called on Enter

Keyboard shortcuts:

  • , increment by step
  • , decrement by step
  • Only digits, ., and - (when min < 0) are accepted

PathInput

A text input with filesystem path completion. Press Tab to complete or cycle through suggestions.

·CODE
import { PathInput } from '@termuijs/ui'

function FileSelector() {
    return (
        <PathInput
            placeholder="/path/to/file"
            cwd={process.cwd()}
            onSubmit={(path) => openFile(path)}
        />
    )
}
PropTypeDefaultDescription
placeholderstring''Hint text
cwdstringprocess.cwd()Base directory for relative paths
showHiddenbooleanfalseInclude .dotfiles in completions
onSubmit(path: string) => void-Called on Enter with the current value

Note: PathInput has a fixed height of 4 rows minimum to show the completion list. Don't use it in height-constrained containers.

Keyboard shortcuts:

  • Tab, complete to the longest common prefix, or show suggestions list
  • Tab again, cycle through completions
  • Shift+Tab, cycle backwards
  • Enter, submit current value
  • Escape, dismiss completions without clearing input

KeyboardShortcuts

Renders a formatted reference card of keyboard bindings. Groups bindings by category, shows key names in bordered boxes.

·CODE
import { KeyboardShortcuts } from '@termuijs/ui'
import type { KeyBinding } from '@termuijs/jsx'

const bindings: KeyBinding[] = [
    { key: 'q',      description: 'Quit',         category: 'General' },
    { key: 'ctrl+c', description: 'Force quit',    category: 'General' },
    { key: '?',      description: 'Show this help', category: 'General' },
    { key: 'up/down', description: 'Navigate',     category: 'Navigation' },
    { key: 'enter',  description: 'Select',        category: 'Navigation' },
    { key: 'tab',    description: 'Next panel',    category: 'Navigation' },
    { key: '/',      description: 'Search',        category: 'Actions' },
    { key: 'r',      description: 'Refresh',       category: 'Actions' },
]

function HelpScreen() {
    return <KeyboardShortcuts bindings={bindings} columns={2} />
}
PropTypeDefaultDescription
bindingsKeyBinding[]RequiredThe shortcuts to display
columnsnumber1Number of columns to lay out groups in
showCategoriesbooleantrueShow group headers

The KeyBinding type comes from @termuijs/jsx. Add a category field to group related shortcuts:

·CODE
import type { KeyBinding } from '@termuijs/jsx'

const binding: KeyBinding = {
    key: 'ctrl+s',
    description: 'Save file',
    category: 'File',         // optional grouping
}

Drawer

A slide-in panel that opens from any screen edge and traps focus until dismissed.

PropTypeDescription
edge'top' | 'bottom' | 'left' | 'right'Which edge the drawer slides from
sizenumberWidth (left/right) or height (top/bottom) in characters
openbooleanWhether the drawer is visible
onClose() => voidCalled when Escape is pressed
·CODE
import { Drawer } from '@termuijs/ui'

function App() {
    const [open, setOpen] = useState(false)
    return <Drawer edge="right" size={40} open={open} onClose={() => setOpen(false)}>{settingsPanel}</Drawer>
}

Wizard

A multi-step form with Next and Back navigation. Each step is a child component.

PropTypeDescription
stepsstring[]Step titles shown in the header
onComplete(data: Record<string, unknown>) => voidCalled when the last step is confirmed
·CODE
import { Wizard } from '@termuijs/ui'

function Setup() {
    return (
        <Wizard steps={['Account', 'Preferences', 'Confirm']} onComplete={handleDone}>
            <AccountStep />
            <PreferencesStep />
            <ConfirmStep />
        </Wizard>
    )
}

RadioGroup

A group of mutually exclusive radio options with keyboard navigation.

PropTypeDescription
optionsArray<{ label: string, value: string, disabled?: boolean }>Available choices
valuestringCurrently selected value
onChange(value: string) => voidCalled when selection changes
·CODE
import { RadioGroup } from '@termuijs/ui'

function ThemePicker() {
    const [theme, setTheme] = useState('dark')
    return (
        <RadioGroup
            value={theme}
            onChange={setTheme}
            options={[{ label: 'Light', value: 'light' }, { label: 'Dark', value: 'dark' }]}
        />
    )
}

TreeSelect

A hierarchical select widget where options are nested in a collapsible tree.

PropTypeDescription
nodesTreeNode[]Nested option tree
valuestring | string[]Selected value(s)
multiplebooleanAllow multi-selection
onChange(value: string | string[]) => voidCalled on selection change
·CODE
import { TreeSelect } from '@termuijs/ui'

function CategoryPicker() {
    return (
        <TreeSelect
            nodes={[{ label: 'Frontend', value: 'fe', children: [{ label: 'React', value: 'react' }] }]}
            onChange={setCategory}
        />
    )
}

TextArea

A multi-line text editor with scrolling.

PropTypeDescription
valuestringInitial content
placeholderstringHint text shown when empty
onChange(value: string) => voidCalled on every edit
onSubmit(value: string) => voidCalled on Ctrl+Enter
·CODE
import { TextArea } from '@termuijs/ui'

function NoteEditor() {
    return <TextArea placeholder="Write your note..." onSubmit={saveNote} />
}

ButtonGroup

A horizontal row of buttons where one can be selected at a time.

PropTypeDescription
buttonsArray<{ label: string, value: string }>Button definitions
valuestringCurrently active button value
onChange(value: string) => voidCalled on selection
·CODE
import { ButtonGroup } from '@termuijs/ui'

function ViewToggle() {
    return (
        <ButtonGroup
            buttons={[{ label: 'List', value: 'list' }, { label: 'Grid', value: 'grid' }]}
            value={view}
            onChange={setView}
        />
    )
}

FilePicker

A file-system browser for selecting files or directories.

PropTypeDescription
cwdstringStarting directory
filter(name: string) => booleanFunction to exclude entries
onSelect(path: string) => voidCalled with the chosen path
·CODE
import { FilePicker } from '@termuijs/ui'

function OpenDialog() {
    return <FilePicker cwd={process.cwd()} onSelect={openFile} />
}

SegmentedControl

A compact row of labeled segments acting as a single-select control.

PropTypeDescription
segmentsstring[]Segment labels
valuestringActive segment label
onChange(value: string) => voidCalled on selection
·CODE
import { SegmentedControl } from '@termuijs/ui'

function SortControl() {
    return <SegmentedControl segments={['Name', 'Date', 'Size']} value={sort} onChange={setSort} />
}

A horizontal menu bar with dropdown submenus and keyboard navigation.

PropTypeDescription
menusArray<{ label: string, items: MenuItem[] }>Top-level menus with their items
onSelect(id: string) => voidCalled with the item id on selection
·CODE
import { MenuBar } from '@termuijs/ui'

function AppMenu() {
    return (
        <MenuBar
            menus={[
                { label: 'File', items: [{ id: 'new', label: 'New' }, { id: 'open', label: 'Open' }] },
                { label: 'Edit', items: [{ id: 'undo', label: 'Undo' }] },
            ]}
            onSelect={handleMenuAction}
        />
    )
}

MaskedInput

A text input that enforces a character-by-character mask pattern, such as dates or phone numbers.

PropTypeDescription
maskstringPattern string where 9 = digit, a = letter, * = any character
valuestringCurrent value
onChange(value: string) => voidCalled on each valid keystroke
·CODE
import { MaskedInput } from '@termuijs/ui'

function DateField() {
    return <MaskedInput mask="99/99/9999" onChange={setDate} />
}

Disclosure

A single toggle-able section with a header button. Similar to Collapsible but styled as an inline disclosure.

PropTypeDescription
labelstringHeader label
openbooleanInitial open state
·CODE
import { Disclosure } from '@termuijs/ui'

function AdvancedSection() {
    return (
        <Disclosure label="Advanced options">
            <AdvancedForm />
        </Disclosure>
    )
}

TagInput

A text input that converts each entered value into a removable tag.

PropTypeDescription
tagsstring[]Current tag values
placeholderstringHint text shown when empty
onChange(tags: string[]) => voidCalled when tags change
·CODE
import { TagInput } from '@termuijs/ui'

function LabelInput() {
    return <TagInput tags={labels} placeholder="Add a label..." onChange={setLabels} />
}

Popover

A floating content panel anchored to a target widget, opened on demand.

PropTypeDescription
openbooleanWhether the popover is visible
onClose() => voidCalled when the popover is dismissed
·CODE
import { Popover } from '@termuijs/ui'

function InfoButton() {
    const [open, setOpen] = useState(false)
    return (
        <Popover open={open} onClose={() => setOpen(false)}>
            <Text>More details here.</Text>
        </Popover>
    )
}

Combobox

A text input combined with a dropdown suggestion list.

PropTypeDescription
optionsstring[]Available suggestions
valuestringCurrent input value
onChange(value: string) => voidCalled on value change
onSelect(value: string) => voidCalled when a suggestion is chosen
·CODE
import { Combobox } from '@termuijs/ui'

function CitySearch() {
    return <Combobox options={cities} value={query} onChange={setQuery} onSelect={setCity} />
}

Slider

A horizontal slider for selecting a numeric value within a range. Arrow keys adjust the value.

PropTypeDescription
valuenumberCurrent position
minnumberMinimum value
maxnumberMaximum value
stepnumberStep size per key press
onChange(value: number) => voidCalled on change
·CODE
import { Slider } from '@termuijs/ui'

function VolumeControl() {
    return <Slider value={volume} min={0} max={100} step={5} onChange={setVolume} />
}

Switch

A boolean toggle displayed as an on/off switch. Space or Enter toggles the state.

PropTypeDescription
checkedbooleanCurrent on/off state
labelstringLabel shown beside the switch
onChange(checked: boolean) => voidCalled on toggle
·CODE
import { Switch } from '@termuijs/ui'

function AutoSaveToggle() {
    return <Switch label="Auto-save" checked={autoSave} onChange={setAutoSave} />
}

Rating

A star or block rating input. Arrow keys change the rating value.

PropTypeDescription
valuenumberCurrent rating
maxnumberMaximum rating (number of stars)
onChange(value: number) => voidCalled on change
·CODE
import { Rating } from '@termuijs/ui'

function Feedback() {
    return <Rating value={rating} max={5} onChange={setRating} />
}

SearchInput

A text input styled for search, with an inline search icon and optional clear button.

PropTypeDescription
valuestringCurrent query string
placeholderstringHint text
onChange(value: string) => voidCalled on each keystroke
onSubmit(value: string) => voidCalled on Enter
·CODE
import { SearchInput } from '@termuijs/ui'

function SearchBar() {
    return <SearchInput placeholder="Search..." value={query} onChange={setQuery} onSubmit={runSearch} />
}

Checkbox

A single boolean checkbox. Space or Enter toggles.

PropTypeDescription
checkedbooleanCurrent state
labelstringLabel beside the checkbox
onChange(checked: boolean) => voidCalled on toggle
·CODE
import { Checkbox } from '@termuijs/ui'

function AgreementField() {
    return <Checkbox label="I agree to the terms" checked={agreed} onChange={setAgreed} />
}

CheckboxGroup

A list of labeled checkboxes for selecting multiple values.

PropTypeDescription
optionsArray<{ label: string, value: string }>Available options
valuestring[]Currently checked values
onChange(value: string[]) => voidCalled when any checkbox changes
·CODE
import { CheckboxGroup } from '@termuijs/ui'

function FeatureFlags() {
    return (
        <CheckboxGroup
            options={[{ label: 'Hot reload', value: 'hmr' }, { label: 'Source maps', value: 'maps' }]}
            value={enabled}
            onChange={setEnabled}
        />
    )
}

See also