@wolf-tui/solid

Build terminal UIs with SolidJS — fine-grained reactivity, no Virtual DOM

Install · Quick Start · Components · Composables · Theming · CSS Styling

The Problem

SolidJS has no terminal rendering target. If you want to build CLI apps with Solid's signal-based reactivity and JSX syntax, you need a custom renderer built on solid-js/universal.

This package provides that renderer, plus 20+ components (inputs, selects, alerts, spinners, progress bars, lists) and composables (useInput, useFocus, etc.) — all using Solid's fine-grained reactivity with createSignal, createEffect, createMemo.

If you've used Ink for React terminal UIs, this is the Solid equivalent. It uses the same layout engine (Taffy) and shared render functions as wolf-tui's React, Vue, Angular, and Svelte adapters.

Install

Scaffold a new project (recommended)

npm create wolf-tui -- --framework solid

Generates a complete project with bundler config, TypeScript, and optional CSS tooling. See create-wolf-tui.

Manual setup

# Runtime dependencies
pnpm add @wolf-tui/solid solid-js

# Build tooling (pick one)
pnpm add -D @wolf-tui/plugin vite vite-plugin-solid
# or
pnpm add -D @wolf-tui/plugin esbuild esbuild-plugin-solid

| Peer dependency | Version | | --------------- | ------- | | solid-js | ^1.9.0 |

Quick Start

import { render, Box, Text, useInput, useApp } from '@wolf-tui/solid'
import { createSignal } from 'solid-js'

function App() {
	const [count, setCount] = createSignal(0)
	const { exit } = useApp()

	useInput((input, key) => {
		if (key.upArrow) setCount((c) => c + 1)
		if (key.downArrow) setCount((c) => Math.max(0, c - 1))
		if (input === 'q') exit()
	})

	return (
		<Box style={{ flexDirection: 'column', padding: 1 }}>
			<Text style={{ color: 'green', fontWeight: 'bold' }}>
				Counter: {count()}
			</Text>
			<Text style={{ color: 'gray' }}>↑/↓ to change, q to quit</Text>
		</Box>
	)
}

// Pass the function reference — not <App />
render(App)

For CSS class-based styling (className="text-green p-1"), see CSS Styling.

TypeScript Setup

// tsconfig.json
{
	"compilerOptions": {
		"jsx": "preserve",
		"jsxImportSource": "solid-js"
	}
}

Vite Configuration

// vite.config.ts
import { defineConfig } from 'vite'
import solidPlugin from 'vite-plugin-solid'
import { wolfie } from '@wolf-tui/plugin/vite'
import { builtinModules } from 'node:module'

const nodeBuiltins = [
	...builtinModules,
	...builtinModules.map((m) => `node:${m}`),
]

export default defineConfig({
	plugins: [
		solidPlugin({
			solid: {
				// Use wolf-tui's universal renderer instead of browser DOM
				moduleName: '@wolf-tui/solid/renderer',
				generate: 'universal',
			},
		}),
		wolfie('solid'),
	],
	resolve: {
		// Prevent Node from resolving solid-js to its server build
		alias: { 'solid-js': '@wolf-tui/solid' },
	},
	build: {
		target: 'node18',
		lib: {
			entry: 'src/index.tsx',
			formats: ['es'],
			fileName: 'index',
		},
		rollupOptions: {
			external: (id) =>
				id === '@wolf-tui/solid' ||
				id.startsWith('@wolf-tui/solid/') ||
				nodeBuiltins.includes(id),
		},
	},
})

esbuild:

// build.mjs
import * as esbuild from 'esbuild'
import { wolfie, generateNativeBanner } from '@wolf-tui/plugin/esbuild'
import { solidPlugin } from 'esbuild-plugin-solid'

await esbuild.build({
	entryPoints: ['src/index.tsx'],
	bundle: true,
	outfile: 'dist/index.cjs',
	platform: 'node',
	format: 'cjs',
	external: ['solid-js', '@wolf-tui/solid'],
	banner: { js: generateNativeBanner('cjs') },
	plugins: [
		solidPlugin({
			solid: {
				generate: 'universal',
				moduleName: '@wolf-tui/solid/renderer',
			},
		}),
		wolfie('solid'),
	],
})

webpack:

// webpack.config.js
import { wolfie } from '@wolf-tui/plugin/webpack'

export default {
	target: 'node',
	entry: './src/index.tsx',
	module: {
		rules: [
			{
				test: /\.tsx?$/,
				use: {
					loader: 'babel-loader',
					options: {
						presets: [
							[
								'babel-preset-solid',
								{
									generate: 'universal',
									moduleName: '@wolf-tui/solid/renderer',
								},
							],
							'@babel/preset-typescript',
						],
					},
				},
				exclude: /node_modules/,
			},
		],
	},
	plugins: [wolfie('solid')],
}

See examples/solid_webpack/ for a complete setup with native binding resolution.

render(component, options?)

Mounts a Solid component to the terminal. First argument is a component function, not a JSX element.

const instance = render(App, {
	stdout: process.stdout,
	stdin: process.stdin,
	maxFps: 30,
})

instance.unmount()

| Option | Type | Default | Description | | ----------------------- | -------------------- | ---------------- | ------------------------ | | stdout | NodeJS.WriteStream | process.stdout | Output stream | | stdin | NodeJS.ReadStream | process.stdin | Input stream | | stderr | NodeJS.WriteStream | process.stderr | Error stream | | maxFps | number | 30 | Maximum render frequency | | debug | boolean | false | Disable frame throttling | | isScreenReaderEnabled | boolean | env-based | Screen reader mode | | theme | ITheme | {} | Component theming |

Components

Layout

| Component | Description | Key features | | -------------- | ------------------------------------------- | ---------------------------------------------------------- | | <Box> | Flexbox/Grid layout container | All CSS-like flex props, style object, class | | <Text> | Styled inline text | Color, bold/italic/underline, wrap modes | | <Newline> | Empty lines | count prop | | <Spacer> | Fills remaining flex space | Pushes siblings apart in flex containers | | <Static> | Renders items once, skips re-renders | Append-only logs, scroll-back history | | <Transform> | Transforms rendered text of children | transform: (line, idx) => string | | <ScrollView> | Fixed-height viewport with clipped overflow | Built-in arrow / PageUp / PageDown / Home / End navigation | | <Table> | Box-drawing table for tabular data | ink-table parity, themable borders/cells, column subset |

Both accept style (inline object) and className (CSS classes via @wolf-tui/plugin).

Box style properties (passed via style):

| Property | Type | Description | | ---------------- | ----------------------------------------------------------------------------- | ------------------- | | flexDirection | 'row' \| 'column' \| 'row-reverse' \| 'column-reverse' | Flex direction | | flexWrap | 'wrap' \| 'nowrap' \| 'wrap-reverse' | Flex wrap | | flexGrow | number | Grow factor | | flexShrink | number | Shrink factor | | alignItems | 'flex-start' \| 'center' \| 'flex-end' \| 'stretch' | Cross-axis | | justifyContent | 'flex-start' \| 'center' \| 'flex-end' \| 'space-between' \| 'space-around' | Main-axis | | gap | number | Gap between items | | width | number \| string | Width | | height | number \| string | Height | | padding | number | Padding (all sides) | | margin | number | Margin (all sides) | | borderStyle | 'single' \| 'double' \| 'round' \| 'classic' | Border style | | borderColor | string | Border color | | overflow | 'visible' \| 'hidden' | Overflow behavior |

Text style properties (passed via style):

| Property | Type | Description | | ----------------- | ---------------------------------------- | ---------------- | | color | string | Text color | | backgroundColor | string | Background color | | fontWeight | 'bold' | Bold text | | fontStyle | 'italic' | Italic text | | textDecoration | 'underline' \| 'line-through' | Decoration | | inverse | boolean | Inverse colors | | textWrap | 'wrap' \| 'truncate' \| 'truncate-end' | Wrap mode |

Renders children inside a fixed-height viewport, clips overflow, and scrolls via marginTop: -offset. Built-in key bindings: ↑/↓ (row), PageUp/PageDown (viewport), Home/End. Adapted from ink-scroll-view.

| Prop | Type | Default | Description | | ----------------------- | -------------------------- | ------- | -------------------------------------------------- | | height | number | — | Viewport height in rows (required) | | offset | number | — | Controlled scroll offset — omit for internal state | | keyBindings | boolean | true | Enable arrows + page + home/end | | onScroll | (offset: number) => void | — | Fires when offset changes | | onContentHeightChange | (height: number) => void | — | Fires when measured content height changes |

Imperative handle (via ref callback): scrollTo(offset), scrollBy(delta), scrollToTop(), scrollToBottom(), getScrollOffset(), getContentHeight(), getViewportHeight().

Display

| Component | Description | Key features | | ----------------- | -------------------------------------- | -------------------------------------------------------------- | | <Alert> | Boxed alert message | variant: success / error / warning / info + title | | <Badge> | Inline coloured label | color prop, children = label | | <Spinner> | Animated loading spinner | 80+ types (dots, line, arc, …), optional label | | <ProgressBar> | Horizontal progress bar | value 0–100, custom characters, themable colors | | <StatusMessage> | One-line status with icon | variant: success / error / warning / info | | <ErrorOverview> | Formatted error display | Pretty stack trace, source frame highlight | | <Gradient> | Coloured text gradient | 13 presets or custom hex stops, per-character interpolation | | <BigText> | ASCII-art figlet-style banner | cfonts engine, multiple fonts, gradients, alignment | | <Timer> | Count-up, countdown, or stopwatch | Lap recording, configurable format, drift-resistant | | <TreeView> | Hierarchical tree with expand/collapse | Single/multi-select, async lazy loading, virtual scroll | | <JsonViewer> | Interactive JSON tree viewer | 16 value types, syntax colouring, circular-reference detection | | <FilePicker> | Filesystem browser with filter mode | Multi-select, symlinks, directory navigation |

Input

| Component | Description | Key features | | ----------------- | ----------------------------------- | ------------------------------------------------------- | | <TextInput> | Single-line text field | onChange / onSubmit, placeholder, mask, suggestions | | <PasswordInput> | Masked text input | Configurable mask character | | <EmailInput> | Email field with domain suggestions | Auto-completes top-100 email domains | | <ConfirmInput> | Yes / No prompt | y / n keys, customizable defaults | | <Select> | Single-selection picker | Keyboard nav, themed indicator, options array | | <MultiSelect> | Multi-selection picker | Toggle with space, submit with enter | | <Combobox> | Fuzzy-search autocomplete dropdown | Two-pass fzf-style matching, cursor nav, autofill |

Lists

| Component | Description | Key features | | ----------------- | ------------- | ------------------------------ | | <OrderedList> | Numbered list | <OrderedListItem> children | | <UnorderedList> | Bulleted list | <UnorderedListItem> children |

// Alert (children as message)
<Alert variant="success" title="Deployed">
  All services are running.
</Alert>

// Badge (children as label)
<Badge color="green">NEW</Badge>

// StatusMessage (children as message)
<StatusMessage variant="success">Saved!</StatusMessage>

// TextInput
<TextInput
  placeholder="Your name..."
  onChange={(value) => console.log(value)}
  onSubmit={(value) => console.log('done:', value)}
/>

// Select (options as prop, not child components)
<Select
  options={[
    { label: 'TypeScript', value: 'ts' },
    { label: 'JavaScript', value: 'js' },
  ]}
  onChange={(value) => console.log('Picked:', value)}
/>

// ProgressBar (0–100, not 0–1)
<ProgressBar value={75} />

// Spinner
<Spinner label="Loading..." />

// Lists
<OrderedList>
  <OrderedListItem>First</OrderedListItem>
  <OrderedListItem>Second</OrderedListItem>
</OrderedList>

// Timer (countdown)
<Timer variant="countdown" durationMs={60000} format="human" onComplete={() => console.log('done')} />

// TreeView
<TreeView data={treeData()} selectionMode="single" onSelectChange={(ids) => console.log(ids)} />

// Combobox
<Combobox options={items()} placeholder="Search..." onSelect={(v) => console.log(v)} />

// JsonViewer
<JsonViewer data={jsonData()} defaultExpandDepth={2} />

// FilePicker
<FilePicker initialPath="." multiSelect onSelect={(paths) => console.log(paths)} />

// Table (ink-table parity)
<Table data={rows()} columns={['id', 'name']} padding={1} />
// ScrollView — uncontrolled, built-in arrows/PageUp/PageDown/Home/End
<ScrollView height={8} onScroll={(o) => console.log('offset', o)}>
  <For each={items()}>{(it) => <Text>{it}</Text>}</For>
</ScrollView>

// ScrollView — imperative handle via ref callback
let handle: IScrollViewHandle | undefined
<ScrollView ref={(h) => (handle = h)} height={8} offset={offset()} onScroll={setOffset} />
// handle?.scrollToBottom()
// Gradient — by preset name
<Gradient name="rainbow">wolf-tui in color</Gradient>

// Gradient — custom stops
<Gradient colors={['#ff3366', '#ffd700']}>Hand-picked stops</Gradient>

Composables

useInput(handler, options?)

Handle keyboard input. Registers immediately (no onMount needed).

import { useInput } from '@wolf-tui/solid'

function App() {
	useInput((input, key) => {
		if (key.upArrow) {
			/* move up */
		}
		if (key.return) {
			/* confirm */
		}
		if (input === 'q') {
			/* quit */
		}
	})

	return <Text>Press q to quit</Text>
}

| Property | Type | Description | | ------------ | --------- | ------------------- | | upArrow | boolean | Up arrow pressed | | downArrow | boolean | Down arrow pressed | | leftArrow | boolean | Left arrow pressed | | rightArrow | boolean | Right arrow pressed | | return | boolean | Enter pressed | | escape | boolean | Escape pressed | | ctrl | boolean | Ctrl held | | shift | boolean | Shift held | | meta | boolean | Meta key held | | tab | boolean | Tab pressed | | backspace | boolean | Backspace pressed | | delete | boolean | Delete pressed | | pageUp | boolean | Page Up pressed | | pageDown | boolean | Page Down pressed | | home | boolean | Home pressed | | end | boolean | End pressed |

The isActive option accepts () => boolean (accessor) to conditionally enable/disable input.

useApp()

Access the app context — primarily for exit().

const { exit } = useApp()

useFocus(options?) / useFocusManager()

Make components focusable and control focus programmatically. isFocused returns a signal accessor — call it as isFocused().

const { isFocused } = useFocus({ autoFocus: true })
const { focusNext, focusPrevious } = useFocusManager()

// In JSX: isFocused() not isFocused
<Text>{isFocused() ? 'Focused!' : 'Not focused'}</Text>

Stream access

| Composable | Returns | | ------------- | ------------------------------------------- | | useStdin() | { stdin, setRawMode, isRawModeSupported } | | useStdout() | { stdout, write } | | useStderr() | { stderr, write } |

Accessibility

| Composable | Returns | Notes | | ---------------------------- | --------- | -------------------------------------------- | | useIsScreenReaderEnabled() | boolean | Render alternative output for screen readers |

import { useIsScreenReaderEnabled, Text } from '@wolf-tui/solid'

function MyView() {
	const srEnabled = useIsScreenReaderEnabled()
	return <Text>{srEnabled ? 'Welcome, screen reader user' : 'Welcome'}</Text>
}

useSpinner — spinner frame animation (returns signal accessor):

const { frame } = useSpinner({ type: 'dots' })
return <Text>{frame()} Loading...</Text>

Headless composables for building custom input UIs:

| Composable | Description | | ----------------------- | --------------------------- | | useTextInputState() | Reactive text input state | | useSelectState() | Reactive select state | | useMultiSelectState() | Reactive multi-select state |

Theming

Customize component appearance via the theme option in render():

import { render, extendTheme, defaultTheme } from '@wolf-tui/solid'

const theme = extendTheme(defaultTheme, {
	components: {
		Spinner: { styles: { spinner: { color: 'cyan' } } },
		Alert: { styles: { container: { borderColor: 'blue' } } },
	},
})

render(App, { theme })

| Export | Description | | ------------------------------ | ---------------------------------------------- | | extendTheme(base, overrides) | Deep-merge overrides into base theme | | defaultTheme | Base theme object | | useComponentTheme(name) | Read theme for a component (inside components) |

CSS Styling

Three approaches, all via @wolf-tui/plugin:

| Method | Usage | | ------------- | -------------------------------------- | | Inline styles | style={{ color: 'green' }} | | Tailwind CSS | className="text-green p-1" + PostCSS | | CSS Modules | className={styles.box} |

All CSS approaches resolve to terminal styles at build time — no runtime CSS engine.

Tailwind CSS:

import './styles.css'
;<Box className="flex-col p-4 gap-2">
	<Text className="text-green-500 font-bold">Tailwind styled</Text>
</Box>

CSS Modules:

import styles from './App.module.css'
;<Box className={styles.container}>
	<Text className={styles.title}>CSS Modules</Text>
</Box>

Key Differences from React

| Aspect | React | Solid | | ------------- | -------------------------- | --------------------------------------- | | Render call | render(<App />) | render(App) — function reference | | State | useState (returns value) | createSignal (returns [get, set]) | | Reading state | count | count() — call the accessor | | Props | Destructure freely | Use splitProps (preserves reactivity) | | Focus state | isFocused (boolean) | isFocused() (signal accessor) |

Testing

Import the testing-aware render from @wolf-tui/solid/testing to drive components headlessly. It wires up virtual stdout/stdin, registers the instance for global cleanup(), and re-exports KEYS, delay, stripAnsi, and cleanup from @wolf-tui/testing-library.

import { afterEach, test, expect } from 'vitest'
import {
	render,
	cleanup,
	KEYS,
	delay,
	stripAnsi,
} from '@wolf-tui/solid/testing'
import { App } from './App'

afterEach(cleanup)

test('navigates the menu', async () => {
	const { stdin, lastFrame } = render(App, { columns: 80, rows: 24 })

	await stdin.write(KEYS.DOWN)
	await stdin.write(KEYS.ENTER)
	await delay(100)

	expect(stripAnsi(lastFrame() ?? '')).toContain('Selection: Option B')
})

Run npm create wolf-tui -- --test to get Vitest, @wolf-tui/testing-library, and a pre-wired test/setup.ts scaffolded automatically. See the testing-library README for the full API.

Part of wolf-tui

This is the Solid adapter for wolf-tui — a framework-agnostic terminal UI library. The same layout engine (Taffy/flexbox) and component render functions power adapters for React, Vue, Angular, and Svelte.

| Bundler | Example | | ------- | ------------------------- | | esbuild | examples/solid_esbuild/ | | webpack | examples/solid_webpack/ |

License

MIT