Virtual Scroll Plugin

The virtual-scroll plugin enables virtualized rendering for large option lists. Instead of rendering all options at once, only the visible options (plus a small buffer) are rendered in the DOM, dramatically improving performance for lists with thousands of items.

Usage

<select
  data-dot-select
  data-plugins="virtual-scroll"
  data-searchable="true"
  data-placeholder="Search 10,000 items..."
>
  <!-- Options can be populated via AJAX or statically -->
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-plugins="virtual-scroll"
      data-searchable="true"
      data-placeholder="Search 10,000 items..."
    >
      <!-- Options can be populated via AJAX or statically -->
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="virtual-scroll"
    data-searchable="true"
    data-placeholder="Search 10,000 items..."
  >
    <!-- Options can be populated via AJAX or statically -->
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

When to Use

Option Count	Recommendation
< 500	Standard rendering is fine
500 - 2,000	Virtual scroll recommended
2,000+	Virtual scroll strongly recommended
10,000+	Virtual scroll required

Configuration

Attribute	Description	Default
data-plugin-virtual-scroll-height	Height of each option row in pixels	36
data-plugin-virtual-scroll-buffer	Number of extra rows to render above/below the visible area	10

<select
  data-dot-select
  data-plugins="virtual-scroll"
  data-plugin-virtual-scroll-height="40"
  data-plugin-virtual-scroll-buffer="15"
  data-searchable="true"
  data-placeholder="Large list..."
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-plugins="virtual-scroll"
      data-plugin-virtual-scroll-height="40"
      data-plugin-virtual-scroll-buffer="15"
      data-searchable="true"
      data-placeholder="Large list..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="virtual-scroll"
    data-plugin-virtual-scroll-height="40"
    data-plugin-virtual-scroll-buffer="15"
    data-searchable="true"
    data-placeholder="Large list..."
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

With AJAX and Pagination

Virtual scroll works alongside AJAX pagination for the best performance with remote data:

<select
  data-dot-select
  data-plugins="virtual-scroll"
  data-ajax-url="/api/products?q={@term}&page={@page}&limit={@pagination_limit}"
  data-pagination="true"
  data-pagination-limit="100"
  data-searchable="true"
  data-placeholder="Search products..."
>
</select>

import { DotSelect } from 'dot-select'

const ds = new DotSelect('select[data-dot-select]')

// API
ds.getValue()
ds.setValue(['value'])
ds.clear()
ds.destroy()

import { useEffect, useRef } from 'react'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

export default function Select() {
  const ref = useRef(null)

  useEffect(() => {
    const ds = new DotSelect(ref.current)
    return () => ds.destroy()
  }, [])

  return (
    <select
      data-dot-select
      data-plugins="virtual-scroll"
      data-ajax-url="/api/products?q={@term}&page={@page}&limit={@pagination_limit}"
      data-pagination="true"
      data-pagination-limit="100"
      data-searchable="true"
      data-placeholder="Search products..."
    >
    </select>
  )
}

<template>
  <select
    data-dot-select
    data-plugins="virtual-scroll"
    data-ajax-url="/api/products?q={@term}&page={@page}&limit={@pagination_limit}"
    data-pagination="true"
    data-pagination-limit="100"
    data-searchable="true"
    data-placeholder="Search products..."
  >
  </select>
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { DotSelect } from 'dot-select'
import 'dot-select/css'

const selectRef = ref(null)
let ds = null

onMounted(() => {
  ds = new DotSelect(selectRef.value)
})

onBeforeUnmount(() => {
  ds?.destroy()
})
</script>

Behavior

• The dropdown renders only the options currently visible in the scroll viewport
• Scrolling dynamically renders and removes option elements
• Search filtering works as normal — the filtered list is also virtualized
• Keyboard navigation (arrow keys) works seamlessly with virtualized options

WARNING

When using virtual scroll, all option rows must have a uniform height. Custom templates with variable-height content may cause rendering issues. Set data-plugin-virtual-scroll-height to match your tallest option.

Performance

Benchmarks with 10,000 static options:

Metric	Without Virtual Scroll	With Virtual Scroll
Initial render	~800ms	~15ms
DOM nodes	10,000+	~40
Memory usage	~45 MB	~5 MB
Scroll performance	Janky	Smooth 60fps