@mikrostack/vir

A high-performance React virtual list component with advanced item maximization and data provider support.

Features

- Virtual Scrolling: Only renders visible items for optimal performance with large datasets
- Dynamic Heights: Supports items with variable heights
- Item Maximization: Expandable/collapsible items with configurable behavior
- TypeScript: Fully typed with comprehensive interfaces
- Smooth Transitions: Built-in transition management for data changes

Installation

``bash
npm install @mikrostack/vir
`

Basic Usage

`tsx
import { VirtualizedList, useDataProvider, ListItem } from '@mikrostack/vir';

const items = [
{ id: '1', title: 'Item 1', description: 'Description 1' },
{ id: '2', title: 'Item 2', description: 'Description 2' },
// ... more items
];

const ItemComponent = ({ id, content, isMaximized, onToggleMaximize, type, metadata }) => (


Control how items behave when expanded using the config prop:

$3

`tsx
interface MaximizationConfig {
mode: 'fixed' | 'natural' | 'percentage' | 'custom';
maxHeight?: number; // for 'custom' mode
containerPercentage?: number; // for 'percentage' mode (default 0.8)
clipOverflow?: boolean; // whether to add overflow:hidden (default true)
neighborSpace?: number; // space to leave for neighboring items (default 120)
}
`

$3

#### 1. Fixed Mode (default)
Items expand to a calculated height based on container percentage:

`tsx
dataProvider={dataProvider}
ItemComponent={ItemComponent}
config={{
maximization: {
mode: 'fixed',
containerPercentage: 0.7, // 70% of container height
clipOverflow: true,
neighborSpace: 100
}
}}
/>
`

#### 2. Natural Mode
Items expand to their natural content height:

`tsx
dataProvider={dataProvider}
ItemComponent={ItemComponent}
config={{
maximization: {
mode: 'natural',
clipOverflow: false // Let content show naturally
}
}}
/>
`

#### 3. Percentage Mode
Explicit percentage-based sizing:

`tsx
dataProvider={dataProvider}
ItemComponent={ItemComponent}
config={{
maximization: {
mode: 'percentage',
containerPercentage: 0.6, // 60% of container
neighborSpace: 80
}
}}
/>
`

#### 4. Custom Mode
Fixed pixel height:

`tsx
dataProvider={dataProvider}
ItemComponent={ItemComponent}
config={{
maximization: {
mode: 'custom',
maxHeight: 300, // Always 300px when expanded
clipOverflow: true
}
}}
/>
`

Data Providers

$3

`tsx
import { useDataProvider } from '@mikrostack/vir';

const items = [...]
const dataProvider = useDataProvider(items, (item) => ({ id: item.name, content: item }));
`

$3

`tsx
import { useQuery } from '@tanstack/react-query';
import { useDataProvider } from '@mikrostack/vir';

const { data, isLoading, isRefetching, error } = useQuery({
queryKey: ['items'],
queryFn: () => ...,
})

const dataProvider = useDataProvider(
data,
(item) => ({ id: item.id, content: item }),
isLoading,
isRefetching,
error,
{
selector: (items) => {...},
dependencies: [deps]
}
);
`

Item Component Interface

Your item components receive these props:

`tsx
interface VirtualizedItemProps {
/* Unique identifier for the item /
id: string;
/* The actual data content, placeholder, or error state /
content: ItemContentState;
/* Whether this item is currently maximized/expanded /
isMaximized: boolean;
/* Function to toggle the maximized state /
onToggleMaximize: () => void;
/* Optional type/category of the item /
type?: string;
/* Optional metadata object of the item /
metadata?: Record;
}
`

For TypeScript users, use the VirtualizedItemComponent type:

`tsx
import {
VirtualizedItemComponent,
isPlaceholderContent,
isRealContent
} from '@mikrostack/vir';

interface MyItemData {
title: string;
description: string;
category: string;
}

const MyItemComponent: VirtualizedItemComponent = ({
id,
content,
isMaximized,
onToggleMaximize,
metadata,
type
}) => {
// Handle loading state
if (isPlaceholderContent(content)) {
return (