Built-in Components

The built-in components are the ratatui-kit reference manual, not a replacement for the tutorials. The tutorials first walk you through state, input exclusivity, and routing. When you start building a real application and need to look up which component to use, what it owns, and what it does not own, come back here.

These components follow the same boundary: business-neutral, composable, and clear about input semantics. Components can help with layout, drawing, input layers, and common interactions, but they do not own your business data model.

Compose first

Build the interface with View, Text, Border, ScrollView, and selection components. Keep business state in page components or hooks.

Then isolate input

Search inputs and modal components create input layers internally. When active, they stop background components from continuing to handle keyboard events.

Virtualize last

Start ordinary lists with Select / MultiSelect; move to VirtualList when the dataset is large or each row is expensive to render.

Layout and text

Component	Purpose	Continue reading
View	Default layout container; splits child regions with flex-like rules	Layout and text primitives
Border	Borders, titles, and local decoration	Layout and text primitives
Center	Centers child content inside a fixed region	Layout and text primitives
Positioned	Special layout for absolute positioning	Layout and text primitives
Fragment	Transparent container that wraps multiple child nodes without creating an independent layout node	Layout and text primitives
Text	Displays a single text segment, Line, Text, or string	Layout and text primitives
WrappedText	Automatically wraps long prose and gives the measured line count back to layout	Long text, logs, prose bodies
ScrollView	Scrollable content container for long prose or long panels	Local scroll regions

WrappedText and ScrollView are the core pair for long-text experiences: the former decides content height, while the latter decides the visible viewport and scrollbars. They come from real reading scenarios, not just examples.

Input and modals

Component	Purpose	Input semantics
Input	Single-line input rendering and low-level editing state	Low-level component, usually driven by a higher-level component
SearchInput	Search/create input with activation key, submit, clear, and editing state	Owns input while editing is open
Modal	Base modal layer, mask, positioning, and layer injection	Must share the same layer with the handler
ConfirmModal	Confirm/cancel flows	Wraps an exclusive input layer internally
AlertModal	Messages and close key	Wraps an exclusive input layer internally
ShortcutInfoModal	Scrollable shortcut help	Wraps an exclusive input layer internally

If you only need business confirmation, a message, or shortcut help, prefer the packaged modal components. Reach for handwritten use_input_layer, use_event_handler(EventScope::Layer(...)), and Modal(layer: Some(...)) only when the modal content has its own complex interaction model.

Selection and virtualization

Component or pattern	Purpose	Continue reading
Select	Ordinary single-select list	Small to medium lists
MultiSelect	Ordinary multi-select list	Small to medium multi-select
TreeSelect	Generic tree selection without file-specific semantics	Grouped, hierarchical, directory-like data
Table	Data-driven table with cell-grid borders, wrapping, and row/column highlight	Bordered/markdown tables and structured grids
VirtualList	Windowed rendering for long lists with custom rows	Thousands to tens of thousands of rows
Virtual Multi Select	Long-list multi-select pattern composed from VirtualList + HashSet	Long-list multi-select where business code owns the selected set

Virtual Multi Select is not a separate component. It is a recommended composition pattern. This is steadier than turning every business selection variant into a built-in component: VirtualList owns only cursor movement, windowing, and visible row rendering, while your business code still owns the selection set.

Real examples

Scenario	Example	VHS
Scroll container	cargo run --example scrollview	docs/tapes/scrollview.tape
Auto-wrapped prose	cargo run --example wrapped_text	docs/tapes/wrapped-text.tape
Single-line input	cargo run --example input	docs/tapes/input.tape
Search/create input	cargo run --example search_input	docs/tapes/search-input.tape
Base modal	cargo run --example modal	docs/tapes/modal.tape
Confirm modal	cargo run --example confirm_modal	docs/tapes/confirm-modal.tape
Alert modal	cargo run --example alert_modal	docs/tapes/alert-modal.tape
Shortcut help	cargo run --example shortcut_info_modal	docs/tapes/shortcut-info-modal.tape
Single select	cargo run --example select	docs/tapes/select.tape
Multi select	cargo run --example multi_select	docs/tapes/multi-select.tape
Tree select	cargo run --example tree_select	docs/tapes/tree-select.tape
Data table	cargo run --example table	docs/tapes/table.tape
Virtual list	cargo run --example virtual_list	docs/tapes/virtual-list.tape
Virtual multi-select pattern	cargo run --example virtual_multi_select	docs/tapes/virtual-multi-select.tape

When adding new built-in components later, add the example, VHS tape, and reference page together. Component behavior described in the docs must be reproducible from a real example.