@oxog/scrollex
v1.0.0TypeScript
Zero-dependency React virtualization library with micro-kernel plugin architecture
reactvirtualizationvirtual-listvirtual-scrollinfinite-scrollvirtual-gridmasonryperformancetypescript
0/weekUpdated 1 months agoMITUnpacked: 1.3 MB
Published by Ersin KOC
npm install @oxog/scrollexScrollex
Zero-dependency React virtualization library with micro-kernel plugin architecture
---
Features
- Zero Dependencies - No runtime dependencies, React is a peer dependency
- High Performance - 100k+ items at 60fps with RAF-based rendering
- Micro-Kernel Architecture - Small core (~3KB) with tree-shakeable plugins
- Variable Heights - Auto-measurement for dynamic content
- Infinite Scroll - Built-in bidirectional infinite loading
- Multiple Layouts - List, Grid, and Masonry components
- TypeScript First - Full type safety with strict mode
- Accessible - Keyboard navigation and ARIA support
Installation
``bash`
npm install @oxog/scrollex
`bash`
yarn add @oxog/scrollex
`bash`
pnpm add @oxog/scrollex
Quick Start
`tsx
import { VirtualList } from '@oxog/scrollex'
function App() {
const items = Array.from({ length: 10000 }, (_, i) => ({
id: i,
name: Item ${i + 1},
}))
return (
itemHeight={50}
height={400}
renderItem={({ item, style }) => (
{item.name}
)}
/>
)
}
`
Components
$3
Efficiently render large lists with fixed or variable heights.
tsx
import { VirtualList } from '@oxog/scrollex'
itemHeight={50}
height={400}
overscan={5}
renderItem={({ item, index, style }) => (
{item.name}
)}
/>
`Variable Heights:
tsx
itemHeight="auto"
estimatedItemHeight={60}
renderItem={({ item, style, measureRef }) => (
{item.content}
)}
/>
`$3
Multi-column grid virtualization.
tsx
import { VirtualGrid } from '@oxog/scrollex'
columns={4}
itemHeight={200}
gap={16}
height={600}
renderItem={({ item, style }) => (
)}
/>
`$3
Pinterest-style masonry layout.
tsx
import { VirtualMasonry } from '@oxog/scrollex'
columns={3}
gap={8}
height={800}
getItemHeight={(item, columnWidth) =>
(item.height / item.width) * columnWidth
}
renderItem={({ item, style, width }) => (
)}
/>
`Hooks
For more control, use the hooks directly:
tsx
import { useRef } from 'react'
import { useVirtualList } from '@oxog/scrollex'function MyList({ items }) {
const containerRef = useRef(null)
const { virtualItems, totalSize, scrollToIndex } = useVirtualList({
count: items.length,
estimatedItemHeight: 50,
containerRef,
overscan: 5,
})
return (
{virtualItems.map((virtualItem) => (
style={{
position: 'absolute',
top: virtualItem.start,
height: virtualItem.size,
width: '100%',
}}
>
{items[virtualItem.index].name}
))}
)
}
`
Plugins
Extend functionality with optional plugins:
tsx
import { VirtualList } from '@oxog/scrollex'
import { infiniteLoaderPlugin, debugPanelPlugin } from '@oxog/scrollex/plugins'
itemHeight={50}
plugins={[
infiniteLoaderPlugin({
threshold: 200,
onLoadMore: async (direction) => {
const newItems = await fetchMore(direction)
setItems(prev => [...prev, ...newItems])
}
}),
debugPanelPlugin({ position: 'bottom-right' }),
]}
renderItem={({ item, style }) => (
{item.name}
)}
/>
`$3
| Plugin | Description |
|--------|-------------|
|
| Core list rendering |
| gridRendererPlugin | Grid layout rendering |
| autoMeasurerPlugin | Automatic height measurement |
| infiniteLoaderPlugin | Infinite scroll loading |
| scrollControllerPlugin | Programmatic scroll control |
| debugPanelPlugin | Visual debugging tools |Infinite Scroll
`tsx
import { useState } from 'react'
import { VirtualList } from '@oxog/scrollex'
import { infiniteLoaderPlugin } from '@oxog/scrollex/plugins'function InfiniteList() {
const [items, setItems] = useState(initialItems)
const [loading, setLoading] = useState(false)
const handleLoadMore = async (direction: 'forward' | 'backward') => {
if (loading) return
setLoading(true)
const newItems = await fetchMoreItems(direction)
setItems(prev =>
direction === 'forward'
? [...prev, ...newItems]
: [...newItems, ...prev]
)
setLoading(false)
}
return (
itemHeight={50}
height={400}
plugins={[
infiniteLoaderPlugin({
threshold: 200,
onLoadMore: handleLoadMore,
})
]}
renderItem={({ item, style }) => (
{item.name}
)}
/>
)
}
`Performance
Scrollex is designed for maximum performance:
- Binary Search - O(log n) visible range calculation
- Measurement Caching - Efficient variable height handling
- RAF Batching - Smooth 60fps rendering
- CSS Containment - Optimized paint and layout
- Tree Shaking - Import only what you need
Tested with 100,000+ items at consistent 60fps.
Browser Support
- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+
Documentation
Full documentation available at scrollex.oxog.dev
- Getting Started
- API Reference
- Examples
- Plugins
Contributing
Contributions are welcome! Please read our Contributing Guide for details.
bash
Clone the repository
git clone https://github.com/ersinkoc/Scrollex.gitInstall dependencies
npm installRun tests
npm testStart development
npm run dev
``Author
Ersin KOC - @ersinkoc
License
MIT License - see the LICENSE file for details.
---
Built with care by Ersin KOC