README.md

title	Components
nav_order	6
has_children	true
permalink	/components/

Components

{: .no_toc }

Most of these are importable from @textui/widgets; the resource and document components come from @textui/documents and are marked as such below. The four primitives are the exception - they are built into @textui/core and always available.

Imported directly, a component works as it is. Calling registerBuiltins(app) is what lets a node graph name 'Table' as data and get one.

Two pages apply to all of them: Base props for what every node accepts, and Nodes for writing one as data rather than as JSX.

The four primitives

The layout engine and the painter only ever see these, which is why adding a component costs a function rather than a case in the engine.

Primitive	What it is
box	The container. Flex layout, background, border, title, footer, scroll
text	A run of text. Wraps, truncates, aligns
canvas	Direct cell painting. The escape hatch charts use
spacer	Empty space, greedy when given flex

Every node also accepts role, label, focusable, onKey, onClick, disabled and selected - so a bare box can take focus and handle keys without a hook.

The catalog

~97 components, and growing.

The four primitives

box	The container. Flex layout, background, border, title and footer.
text	A run of text. Wraps, truncates and aligns within its box.
canvas	Direct cell painting. The escape hatch charts and gauges use.
spacer	Empty space. Sized, or greedy when given flex.

Layout

Row	Horizontal flex container.
Column	Vertical flex container.
Center	Centres its children.
Grid	Equal-width columns, wrapping into rows.
Panel	Titled region. Bordered or airy, following the theme.
Divider	A rule, optionally labelled.
Stack	Column with themed spacing.
ScrollView	Scrolling viewport with keyboard and wheel support.
Splitter	Two panes with a divider.

Display

Heading	Section heading, three levels.
Label	Secondary text with a semantic tone.
Badge	Small status marker; carries a glyph as well as a colour.
StatusDot	The shared status vocabulary: up, degraded, down.
Card	Bordered block with a title.
ColorText	Multiline text coloured cell by cell - a ramp, a palette per line, or a function.
Marquee	Text too long for its box, read by sliding it while it has the cursor.

Data

KeyValue	Aligned label/value pairs.
Timeline	Ordered events down a rail.
List	Selectable rows with keyboard navigation.
Table	Columns that drop by priority as space runs out.
Tree	Expandable hierarchy.
Pagination	Page of pages.
LogViewer	Streaming lines that follow the tail until you scroll.
CodeViewer	A scrolling, syntax-coloured file viewer.
MarkdownView	Markdown drawn into the width it was given. Does not scroll.
Feed	A viewport over entries of any height, with a cursor and a tail it follows.

Charts

Sparkline	One row of block glyphs; eight levels per cell.
BarChart	Labelled bars, horizontal or vertical.
LineChart	Braille plot at 2x4 the cell resolution.
AreaChart	A line chart, filled.
Histogram	Bucketed distribution.
Gauge	A reading against thresholds.
Heatmap	A grid of intensities.

Feedback and status

Alert	A message with an icon and a tone.
Progress	Determinate or indeterminate bar, sub-cell resolution.
Spinner	Animated activity indicator.
Skeleton	Loading placeholder.
EmptyState	Nothing here, and what to do about it.
ErrorState	A failure, with its message.

Controls

Button	Focusable action.
Checkbox	On, off, or mixed.
Switch	Two-state toggle with words, not only colour.
RadioGroup	One of several.
Slider	A value along a track.
TextArea	A field that is a paragraph: grows, scrolls, and gives back the keys it does not want.
TextInput	Single-line text with a real caret.
Select	Pick from a list, collapsed or open.
SearchBox	A text field that looks like search.

Forms

Form	Provides form state to its fields.
Field	Label, control and error, aligned.
FormSection	A titled group of fields.
FormActions	Submit and cancel.
DangerZone	Destructive action, fenced off.

Navigation

Tabs	Tab strip or segmented control.
Breadcrumb	Where you are, collapsing in the middle when narrow.
Menu	Keyboard-driven list of actions.
StatusBar	One line, segments left and right.
Toolbar	A row of actions.
KeyHints	What the keys do, right now.
Wizard	Ordered steps with progress.

Overlays

Dialog	Modal box with actions; traps focus and restores it.
PromptDialog	One-field dialog behind the prompt helper.
PathPicker	Walk the resource tree and pick a file or a folder.
Tooltip	Small anchored hint.
Toast	Transient notification.
ToastHost	Where toasts stack.
LayerScope	The focus scope a layer lives in; makes trapFocus real.
CommandPalette	Fuzzy search over the command registry.

Surfaces and shells

SurfaceArea	Renders one surface through its active layout.
MountView	Renders one mount target.
SingleLayout	Only the active mount.
TabsLayout	Tab strip plus the active mount.
StackLayout	All mounts, stacked with headings.
SplitLayout	All mounts, side by side.
BarLayout	All mounts on one line.
RailLayout	Icons only.
InlineLayout	All mounts, no chrome.
PlainShell	Main and status, no frame.
ConsoleShell	Dense bordered operator console.
PaperShell	Airy and borderless.
WorkbenchShell	Full frame: rail, sidebar, tabs, panel, status.

Resources and documents

ResourcePanel	A place a resource is shown, by whichever renderer is registered for it.
TextViewer documents	Plain text with a line-number gutter.
MarkdownViewer documents	Headings, lists, rules, quotes and fenced code.
FallbackViewer documents	What an unregistered kind gets.
ResourceView documents	Displays a resource through the registry.
ResourceExplorer documents	Browse and open resources.
ResourceActions documents	Actions registered for a kind.
ResourceOpenWith documents	Choose among registered viewers.
ResourceBreadcrumb documents	The path to a resource.
JsonViewer documents	JSON source, coloured by the registered highlighter.
JsonTreeViewer documents	JSON as an expandable structure.
CodeEditor documents	Edit a document buffer, with a caret that has a column.