# @mwillbanks/tuil-virtual

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

Terminal-aware virtual lists and viewport primitives for tuil.



## Overview [#overview]

Terminal-aware virtual lists and viewport primitives for tuil.

`@mwillbanks/tuil-virtual` 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-virtual
    ```
  </CodeBlockTab>

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

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

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

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

Terminal virtualization adapts TanStack Virtual measurements to rows and columns, returning visible indexes, overscan, before/after space, and fixed-width text fitting.

<Mermaid
  chart="flowchart LR
  S0[&#x22;measure viewport&#x22;]
  S1[&#x22;project range&#x22;]
  S2[&#x22;render visible rows&#x22;]
  S3[&#x22;remeasure&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3"
/>

## API [#api]

| API                                                                                               | Signature                              | Description                                  |
| ------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------- |
| [`getVisibleTerminalIndexes`](/tuil/docs/reference/packages/virtual/api/get-visible-terminal-indexes)  | `function getVisibleTerminalIndexes`   | Public function getVisibleTerminalIndexes.   |
| [`TerminalVirtualizerOptions`](/tuil/docs/reference/packages/virtual/api/terminal-virtualizer-options) | `interface TerminalVirtualizerOptions` | Public interface TerminalVirtualizerOptions. |
| [`TerminalVirtualRange`](/tuil/docs/reference/packages/virtual/api/terminal-virtual-range)             | `interface TerminalVirtualRange`       | Public interface TerminalVirtualRange.       |

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

Virtualization is pure or subscription-driven at the component layer; no global events are emitted.

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

## Example [#example]

```tsx
const range = useTerminalVirtualizer({ count: 10_000, viewportSize: 20, scrollOffset });
```

## Related [#related]

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