# @mwillbanks/tuil-ink

Source: /tuil/docs/reference/packages/ink
Locale: en

Ink renderer, terminal input, semantics, primitives, and overlays for tuil.



## Overview [#overview]

Ink renderer, terminal input, semantics, primitives, and overlays for tuil.

`@mwillbanks/tuil-ink` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-ink
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-ink
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-ink
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-ink
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

The Ink adapter composes runtime, theme, focus, hotkeys, semantics, overlays, and terminal input around Ink rendering. It supports interactive output, static output, and capability-aware fallbacks.

<Mermaid
  chart="flowchart LR
  S0[&#x22;create runtime tree&#x22;]
  S1[&#x22;attach input&#x22;]
  S2[&#x22;render&#x22;]
  S3[&#x22;wait or snapshot&#x22;]
  S4[&#x22;unmount&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## API [#api]

| API                                                                                                      | Signature                                | Description                                    |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------- |
| [`Alert`](/tuil/docs/reference/packages/ink/api/alert)                                                        | `function Alert`                         | Public function Alert.                         |
| [`AlertProps`](/tuil/docs/reference/packages/ink/api/alert-props)                                             | `interface AlertProps`                   | Public interface AlertProps.                   |
| [`AppBar`](/tuil/docs/reference/packages/ink/api/app-bar)                                                     | `function AppBar`                        | Public function AppBar.                        |
| [`AppShell`](/tuil/docs/reference/packages/ink/api/app-shell)                                                 | `function AppShell`                      | Public function AppShell.                      |
| [`Badge`](/tuil/docs/reference/packages/ink/api/badge)                                                        | `function Badge`                         | Public function Badge.                         |
| [`BadgeProps`](/tuil/docs/reference/packages/ink/api/badge-props)                                             | `interface BadgeProps`                   | Public interface BadgeProps.                   |
| [`Box`](/tuil/docs/reference/packages/ink/api/box)                                                            | `function Box`                           | Public function Box.                           |
| [`BoxProps`](/tuil/docs/reference/packages/ink/api/box-props)                                                 | `interface BoxProps`                     | Public interface BoxProps.                     |
| [`Button`](/tuil/docs/reference/packages/ink/api/button)                                                      | `function Button`                        | Public function Button.                        |
| [`ButtonProps`](/tuil/docs/reference/packages/ink/api/button-props)                                           | `interface ButtonProps`                  | Public interface ButtonProps.                  |
| [`CommonComponentProps`](/tuil/docs/reference/packages/ink/api/common-component-props)                        | `interface CommonComponentProps`         | Public interface CommonComponentProps.         |
| [`Container`](/tuil/docs/reference/packages/ink/api/container)                                                | `function Container`                     | Public function Container.                     |
| [`ContainerProps`](/tuil/docs/reference/packages/ink/api/container-props)                                     | `interface ContainerProps`               | Public interface ContainerProps.               |
| [`createRuntimeElement`](/tuil/docs/reference/packages/ink/api/create-runtime-element)                        | `function createRuntimeElement`          | Public function createRuntimeElement.          |
| [`DismissableLayer`](/tuil/docs/reference/packages/ink/api/dismissable-layer)                                 | `function DismissableLayer`              | Public function DismissableLayer.              |
| [`Divider`](/tuil/docs/reference/packages/ink/api/divider)                                                    | `function Divider`                       | Public function Divider.                       |
| [`DividerProps`](/tuil/docs/reference/packages/ink/api/divider-props)                                         | `interface DividerProps`                 | Public interface DividerProps.                 |
| [`escapeTerminalControlCharacters`](/tuil/docs/reference/packages/ink/api/escape-terminal-control-characters) | `export escapeTerminalControlCharacters` | Public export escapeTerminalControlCharacters. |
| [`ExternalSnapshotStore`](/tuil/docs/reference/packages/ink/api/external-snapshot-store)                      | `interface ExternalSnapshotStore`        | Public interface ExternalSnapshotStore.        |
| [`Heading`](/tuil/docs/reference/packages/ink/api/heading)                                                    | `function Heading`                       | Public function Heading.                       |
| [`HeadingProps`](/tuil/docs/reference/packages/ink/api/heading-props)                                         | `interface HeadingProps`                 | Public interface HeadingProps.                 |
| [`HStack`](/tuil/docs/reference/packages/ink/api/hstack)                                                      | `function HStack`                        | Public function HStack.                        |
| [`InkRendererBackend`](/tuil/docs/reference/packages/ink/api/ink-renderer-backend)                            | `class InkRendererBackend`               | Public class InkRendererBackend.               |
| [`InkRendererTree`](/tuil/docs/reference/packages/ink/api/ink-renderer-tree)                                  | `type InkRendererTree`                   | Public type InkRendererTree.                   |
| [`Overlay`](/tuil/docs/reference/packages/ink/api/overlay)                                                    | `function Overlay`                       | Public function Overlay.                       |
| [`OverlayProps`](/tuil/docs/reference/packages/ink/api/overlay-props)                                         | `interface OverlayProps`                 | Public interface OverlayProps.                 |
| [`OverlayProvider`](/tuil/docs/reference/packages/ink/api/overlay-provider)                                   | `function OverlayProvider`               | Public function OverlayProvider.               |
| [`OverlayStatus`](/tuil/docs/reference/packages/ink/api/overlay-status)                                       | `interface OverlayStatus`                | Public interface OverlayStatus.                |
| [`PointerEventBinding`](/tuil/docs/reference/packages/ink/api/pointer-event-binding)                          | `interface PointerEventBinding`          | Public interface PointerEventBinding.          |
| [`Progress`](/tuil/docs/reference/packages/ink/api/progress)                                                  | `function Progress`                      | Public function Progress.                      |
| [`ProgressProps`](/tuil/docs/reference/packages/ink/api/progress-props)                                       | `interface ProgressProps`                | Public interface ProgressProps.                |
| [`render`](/tuil/docs/reference/packages/ink/api/render)                                                      | `function render`                        | Public function render.                        |
| [`renderStatic`](/tuil/docs/reference/packages/ink/api/render-static)                                         | `function renderStatic`                  | Public function renderStatic.                  |
| [`renderTerminalImage`](/tuil/docs/reference/packages/ink/api/render-terminal-image)                          | `function renderTerminalImage`           | Public function renderTerminalImage.           |
| [`resolveSemanticNode`](/tuil/docs/reference/packages/ink/api/resolve-semantic-node)                          | `function resolveSemanticNode`           | Public function resolveSemanticNode.           |
| [`ResponsiveStack`](/tuil/docs/reference/packages/ink/api/responsive-stack)                                   | `function ResponsiveStack`               | Public function ResponsiveStack.               |
| [`ResponsiveStackProps`](/tuil/docs/reference/packages/ink/api/responsive-stack-props)                        | `interface ResponsiveStackProps`         | Public interface ResponsiveStackProps.         |
| [`SemanticNode`](/tuil/docs/reference/packages/ink/api/semantic-node)                                         | `interface SemanticNode`                 | Public interface SemanticNode.                 |
| [`SemanticProvider`](/tuil/docs/reference/packages/ink/api/semantic-provider)                                 | `function SemanticProvider`              | Public function SemanticProvider.              |
| [`SemanticRegistry`](/tuil/docs/reference/packages/ink/api/semantic-registry)                                 | `class SemanticRegistry`                 | Public class SemanticRegistry.                 |
| [`Spinner`](/tuil/docs/reference/packages/ink/api/spinner)                                                    | `function Spinner`                       | Public function Spinner.                       |
| [`SpinnerProps`](/tuil/docs/reference/packages/ink/api/spinner-props)                                         | `interface SpinnerProps`                 | Public interface SpinnerProps.                 |
| [`Stack`](/tuil/docs/reference/packages/ink/api/stack)                                                        | `function Stack`                         | Public function Stack.                         |
| [`StackProps`](/tuil/docs/reference/packages/ink/api/stack-props)                                             | `interface StackProps`                   | Public interface StackProps.                   |
| [`StatusBar`](/tuil/docs/reference/packages/ink/api/status-bar)                                               | `function StatusBar`                     | Public function StatusBar.                     |
| [`TerminalImage`](/tuil/docs/reference/packages/ink/api/terminal-image)                                       | `function TerminalImage`                 | Public function TerminalImage.                 |
| [`TerminalImageProps`](/tuil/docs/reference/packages/ink/api/terminal-image-props)                            | `interface TerminalImageProps`           | Public interface TerminalImageProps.           |
| [`TerminalImageSource`](/tuil/docs/reference/packages/ink/api/terminal-image-source)                          | `interface TerminalImageSource`          | Public interface TerminalImageSource.          |
| [`TerminalInputHandler`](/tuil/docs/reference/packages/ink/api/terminal-input-handler)                        | `export TerminalInputHandler`            | Public export TerminalInputHandler.            |
| [`TerminalInputLayer`](/tuil/docs/reference/packages/ink/api/terminal-input-layer)                            | `export TerminalInputLayer`              | Public export TerminalInputLayer.              |
| [`TerminalScrollAreaOptions`](/tuil/docs/reference/packages/ink/api/terminal-scroll-area-options)             | `interface TerminalScrollAreaOptions`    | Public interface TerminalScrollAreaOptions.    |
| [`TerminalSemanticNode`](/tuil/docs/reference/packages/ink/api/terminal-semantic-node)                        | `function TerminalSemanticNode`          | Public function TerminalSemanticNode.          |
| [`TerminalSemanticNodeProps`](/tuil/docs/reference/packages/ink/api/terminal-semantic-node-props)             | `interface TerminalSemanticNodeProps`    | Public interface TerminalSemanticNodeProps.    |
| [`TerminalSize`](/tuil/docs/reference/packages/ink/api/terminal-size)                                         | `interface TerminalSize`                 | Public interface TerminalSize.                 |
| [`Text`](/tuil/docs/reference/packages/ink/api/text)                                                          | `function Text`                          | Public function Text.                          |
| [`TextProps`](/tuil/docs/reference/packages/ink/api/text-props)                                               | `interface TextProps`                    | Public interface TextProps.                    |
| [`TuilRenderInstance`](/tuil/docs/reference/packages/ink/api/tuil-render-instance)                            | `interface TuilRenderInstance`           | Public interface TuilRenderInstance.           |
| [`TuilRenderOptions`](/tuil/docs/reference/packages/ink/api/tuil-render-options)                              | `interface TuilRenderOptions`            | Public interface TuilRenderOptions.            |
| [`useOptionalExternalStore`](/tuil/docs/reference/packages/ink/api/use-optional-external-store)               | `function useOptionalExternalStore`      | Public function useOptionalExternalStore.      |
| [`useOverlayStatus`](/tuil/docs/reference/packages/ink/api/use-overlay-status)                                | `function useOverlayStatus`              | Public function useOverlayStatus.              |
| [`usePointerCapture`](/tuil/docs/reference/packages/ink/api/use-pointer-capture)                              | `function usePointerCapture`             | Public function usePointerCapture.             |
| [`usePointerEvent`](/tuil/docs/reference/packages/ink/api/use-pointer-event)                                  | `function usePointerEvent`               | Public function usePointerEvent.               |
| [`usePointerEvents`](/tuil/docs/reference/packages/ink/api/use-pointer-events)                                | `function usePointerEvents`              | Public function usePointerEvents.              |
| [`useSemanticNode`](/tuil/docs/reference/packages/ink/api/use-semantic-node)                                  | `function useSemanticNode`               | Public function useSemanticNode.               |
| [`useSemanticRegistry`](/tuil/docs/reference/packages/ink/api/use-semantic-registry)                          | `function useSemanticRegistry`           | Public function useSemanticRegistry.           |
| [`useTerminalInput`](/tuil/docs/reference/packages/ink/api/use-terminal-input)                                | `export useTerminalInput`                | Public export useTerminalInput.                |
| [`useTerminalScrollArea`](/tuil/docs/reference/packages/ink/api/use-terminal-scroll-area)                     | `function useTerminalScrollArea`         | Public function useTerminalScrollArea.         |
| [`useTerminalSize`](/tuil/docs/reference/packages/ink/api/use-terminal-size)                                  | `function useTerminalSize`               | Public function useTerminalSize.               |
| [`useTerminalViewport`](/tuil/docs/reference/packages/ink/api/use-terminal-viewport)                          | `function useTerminalViewport`           | Public function useTerminalViewport.           |
| [`VStack`](/tuil/docs/reference/packages/ink/api/vstack)                                                      | `function VStack`                        | Public function VStack.                        |

## Events and lifecycle [#events-and-lifecycle]

Input first flows through overlay handlers, scoped terminal handlers, hotkeys, then focus traversal. Application events remain on the runtime event bus.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { render } from "@mwillbanks/tuil-ink";

const instance = render(<App />, { app });
await instance.waitUntilExit();
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)