Documentation

Data displayGlass surface

VirtualList

Frames long scrollable collections for virtualization adapters.

View preview API reference View in Figma

FrameworksAstro · React · Elements

Registry commandlumen add VirtualList

InteractionEnhanced runtime

Design sourceLinked component node

See it in context

Preview

Deployment #200

Deployment #199

Deployment #198

Deployment #197

Deployment #196

Deployment #195

Deployment #194

Deployment #193

Deployment #192

Deployment #191

Deployment #190

Deployment #189

Deployment #188

Deployment #187

Deployment #186

Deployment #185

Deployment #184

Deployment #183

Deployment #182

Deployment #181

Deployment #180

Deployment #179

Deployment #178

Deployment #177

Deployment #176

Deployment #175

Deployment #174

Deployment #173

Deployment #172

Deployment #171

Deployment #170

Deployment #169

Deployment #168

Deployment #167

Deployment #166

Deployment #165

Deployment #164

Deployment #163

Deployment #162

Deployment #161

Deployment #160

Deployment #159

Deployment #158

Deployment #157

Deployment #156

Deployment #155

Deployment #154

Deployment #153

Deployment #152

Deployment #151

Deployment #150

Deployment #149

Deployment #148

Deployment #147

Deployment #146

Deployment #145

Deployment #144

Deployment #143

Deployment #142

Deployment #141

Deployment #140

Deployment #139

Deployment #138

Deployment #137

Deployment #136

Deployment #135

Deployment #134

Deployment #133

Deployment #132

Deployment #131

Deployment #130

Deployment #129

Deployment #128

Deployment #127

Deployment #126

Deployment #125

Deployment #124

Deployment #123

Deployment #122

Deployment #121

Deployment #120

Deployment #119

Deployment #118

Deployment #117

Deployment #116

Deployment #115

Deployment #114

Deployment #113

Deployment #112

Deployment #111

Deployment #110

Deployment #109

Deployment #108

Deployment #107

Deployment #106

Deployment #105

Deployment #104

Deployment #103

Deployment #102

Deployment #101

Deployment #100

Deployment #99

Deployment #98

Deployment #97

Deployment #96

Deployment #95

Deployment #94

Deployment #93

Deployment #92

Deployment #91

Deployment #90

Deployment #89

Deployment #88

Deployment #87

Deployment #86

Deployment #85

Deployment #84

Deployment #83

Deployment #82

Deployment #81

Deployment #80

Deployment #79

Deployment #78

Deployment #77

Deployment #76

Deployment #75

Deployment #74

Deployment #73

Deployment #72

Deployment #71

Deployment #70

Deployment #69

Deployment #68

Deployment #67

Deployment #66

Deployment #65

Deployment #64

Deployment #63

Deployment #62

Deployment #61

Deployment #60

Deployment #59

Deployment #58

Deployment #57

Deployment #56

Deployment #55

Deployment #54

Deployment #53

Deployment #52

Deployment #51

Deployment #50

Deployment #49

Deployment #48

Deployment #47

Deployment #46

Deployment #45

Deployment #44

Deployment #43

Deployment #42

Deployment #41

Deployment #40

Deployment #39

Deployment #38

Deployment #37

Deployment #36

Deployment #35

Deployment #34

Deployment #33

Deployment #32

Deployment #31

Deployment #30

Deployment #29

Deployment #28

Deployment #27

Deployment #26

Deployment #25

Deployment #24

Deployment #23

Deployment #22

Deployment #21

Deployment #20

Deployment #19

Deployment #18

Deployment #17

Deployment #16

Deployment #15

Deployment #14

Deployment #13

Deployment #12

Deployment #11

Deployment #10

Deployment #9

Deployment #8

Deployment #7

Deployment #6

Deployment #5

Deployment #4

Deployment #3

Deployment #2

Deployment #1

Copy a working example

Usage

Astro examples assume UIPrimitives is mounted once in your root layout. Do not add the runtime next to each component instance.

---
import { VirtualList } from '@santi020k/lumen-astro'

const rows = Array.from({ length: 200 }, (_, index) => `Deployment #${200 - index}`)
---

{/* 200 rows, but only the visible slice is rendered while scrolling. */}
<VirtualList aria-label="Deployments" data-ui-item-size="44" style="--ui-list-height: 12rem">
  {rows.map(row => <div>{row}</div>)}
</VirtualList>

---
import { VirtualList } from '@santi020k/lumen-astro'

const rows = Array.from({ length: 200 }, (_, index) => `Deployment #${200 - index}`)
---

{/* 200 rows, but only the visible slice is rendered while scrolling. */}
<VirtualList aria-label="Deployments" data-ui-item-size="44" style="--ui-list-height: 12rem">
  {rows.map(row => <div>{row}</div>)}
</VirtualList>

import { VirtualList } from '@santi020k/lumen-react'

export const Example = () => (
  <>
    {/* 200 rows, but only the visible slice is rendered while scrolling. */}
    <VirtualList aria-label="Deployments" data-ui-item-size="44" style={{ -UiListHeight: '12rem' }}>
      {rows.map(row => <div>{row}</div>)}
    </VirtualList>
  </>
)

import { VirtualList } from '@santi020k/lumen-react'

export const Example = () => (
  <>
    {/* 200 rows, but only the visible slice is rendered while scrolling. */}
    <VirtualList aria-label="Deployments" data-ui-item-size="44" style={{ -UiListHeight: '12rem' }}>
      {rows.map(row => <div>{row}</div>)}
    </VirtualList>
  </>
)

<script type="module">
  import { defineLumenElements } from '@santi020k/lumen-elements/define'

  defineLumenElements()
</script>

{/* 200 rows, but only the visible slice is rendered while scrolling. */}
<lumen-virtual-list aria-label="Deployments" data-ui-item-size="44" style="--ui-list-height: 12rem">
  {rows.map(row => <div>{row}</div>)}
</lumen-virtual-list>

<script type="module">
  import { defineLumenElements } from '@santi020k/lumen-elements/define'

  defineLumenElements()
</script>

{/* 200 rows, but only the visible slice is rendered while scrolling. */}
<lumen-virtual-list aria-label="Deployments" data-ui-item-size="44" style="--ui-list-height: 12rem">
  {rows.map(row => <div>{row}</div>)}
</lumen-virtual-list>

Choose your target

Add this component

Choose the package for your runtime. All adapters share the Lumen stylesheet. Use the matching registry command when you want a local wrapper for that framework.

pnpm add @santi020k/lumen-astro

pnpm add @santi020k/lumen-astro

lumen add VirtualList

lumen add VirtualList

pnpm add @santi020k/lumen-react

pnpm add @santi020k/lumen-react

lumen add VirtualList --target react

lumen add VirtualList --target react

pnpm add @santi020k/lumen-elements

pnpm add @santi020k/lumen-elements

lumen add VirtualList --target elements

lumen add VirtualList --target elements

Glass

Add the glass prop to apply the shared blur, saturation, border, and highlight tokens. Glass reads best over vivid content, so place the surface above imagery or color.

Frosted row 1

Frosted row 2

Frosted row 3

Frosted row 4

---
import { VirtualList } from '@santi020k/lumen-astro'
---

<div class="docs-glass-demo">
  <VirtualList glass style="--ui-list-height: 12rem;">
    <div>Frosted row 1</div>
    <div>Frosted row 2</div>
    <div>Frosted row 3</div>
    <div>Frosted row 4</div>
  </VirtualList>
</div>

---
import { VirtualList } from '@santi020k/lumen-astro'
---

<div class="docs-glass-demo">
  <VirtualList glass style="--ui-list-height: 12rem;">
    <div>Frosted row 1</div>
    <div>Frosted row 2</div>
    <div>Frosted row 3</div>
    <div>Frosted row 4</div>
  </VirtualList>
</div>

import { VirtualList } from '@santi020k/lumen-react'

export const Example = () => (
  <>
    <div className="docs-glass-demo">
      <VirtualList glass style={{ -UiListHeight: '12rem' }}>
        <div>Frosted row 1</div>
        <div>Frosted row 2</div>
        <div>Frosted row 3</div>
        <div>Frosted row 4</div>
      </VirtualList>
    </div>
  </>
)

import { VirtualList } from '@santi020k/lumen-react'

export const Example = () => (
  <>
    <div className="docs-glass-demo">
      <VirtualList glass style={{ -UiListHeight: '12rem' }}>
        <div>Frosted row 1</div>
        <div>Frosted row 2</div>
        <div>Frosted row 3</div>
        <div>Frosted row 4</div>
      </VirtualList>
    </div>
  </>
)

<script type="module">
  import { defineLumenElements } from '@santi020k/lumen-elements/define'

  defineLumenElements()
</script>

<div class="docs-glass-demo">
  <lumen-virtual-list glass style="--ui-list-height: 12rem;">
    <div>Frosted row 1</div>
    <div>Frosted row 2</div>
    <div>Frosted row 3</div>
    <div>Frosted row 4</div>
  </lumen-virtual-list>
</div>

<script type="module">
  import { defineLumenElements } from '@santi020k/lumen-elements/define'

  defineLumenElements()
</script>

<div class="docs-glass-demo">
  <lumen-virtual-list glass style="--ui-list-height: 12rem;">
    <div>Frosted row 1</div>
    <div>Frosted row 2</div>
    <div>Frosted row 3</div>
    <div>Frosted row 4</div>
  </lumen-virtual-list>
</div>

API reference

Lumen-specific props and runtime attributes for the Astro primitive. React props follow the same names; Elements use equivalent kebab-case attributes where custom elements expose them.

Attribute	Values	Default	Description
glass	boolean \| "subtle" \| "strong"	false	Applies the tokenized liquid-glass surface treatment with backdrop-filter fallbacks; "subtle" and "strong" adjust the fill intensity.
itemSize	number \| string	-	Fixed size for items if all are uniform height/width. Used for virtual scroll calculation.
overscan	number \| string	-	Number of items to render outside the viewport.
class, className	string	""	Merges custom classes with the generated ui-* root classes.
...native attributes	HTML attributes	-	Forwards standard attributes to the root element unless the component consumes them.

Runtime events

CustomEvents dispatched by the Astro UIPrimitives runtime for this component.

Event	Target	Detail	When
ui:virtual-list-range	VirtualList root ([data-ui-virtual-list])	{ startIndex: number, endIndex: number }	Fires when the virtual list calculates its visible range on initialization or scroll.