Virtualization

Learn how to efficiently render large datasets with Akar, powered by @tanstack/virtual.
What is Virtualization?Virtualization is a technique used to efficiently render large lists or tree structures by only rendering the items currently visible in the viewport. This approach significantly improves performance and reduces memory usage, especially when dealing with thousands of items.

Benefits of Using Virtualization

  • [object Object]
  • [object Object]
  • [object Object]

Customization Options

All virtualizer (ACombobox, AListbox, and ATree) components offer the following props and customization:

  • Custom item rendering: Flexibility to render complex item structures
  • estimateSize: Set estimate item heights for static or dynamic item
  • overscan: Control the number of items rendered outside the visible area
  • textContent: Text content for each item to achieve type-ahead feature

Usage

Here's a few important note to make sure virtualization works!

  1. A fixed height/max-height wrapping <Virtualizer />.
  2. Consistent item height, and set the estimateSize props appropriately.
  3. Set textContent props to make sure type-ahead acceessibility.

Example

<script setup>
import { AComboboxContent, AComboboxItem, AComboboxRoot, AComboboxViewport, AComboboxVirtualizer } from 'akar';

const items = [
  // … large array of items
];
</script>

<template>
  <AComboboxRoot>
    …
    <AComboboxContent>
      <!-- Make sure to set a height for Virtualizer's parent element -->
      <AComboboxViewport class="max-h-80 overflow-y-auto">
        <AComboboxVirtualizer
          v-slot="{ option }"
          :options="items"
          :estimate-size="25"
          :text-content="(opt) => opt.label"
        >
          <AComboboxItem :value="option">
            {{ option.label }}
          </AComboboxItem>
        </AComboboxVirtualizer>
      </AComboboxViewport>
    </AComboboxContent>
  </AComboboxRoot>
</template>

Common issue

Virtualization is not working

Do ensure that <Virtualizer>'s parent element has a defined height!

<template>
  <AComboboxRoot>
    …
    <AComboboxContent>
      <!-- Height must be defined -->
      <AComboboxViewport class="max-h-80 overflow-y-auto">
        <AComboboxVirtualizer>
          …
        </AComboboxVirtualizer>
      </AComboboxViewport>
    </AComboboxContent>
  </AComboboxRoot>
</template>