### Live Example: Basic DataTable Setup

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/data-table/docs/3.columns/01.defining-columns.md

This live example demonstrates a basic `DataTable` setup with several columns, including custom headers and cell renderers for product name, category, and stock. It utilizes `localModel` for data management.

```tsx
import { DataTable, DataTableCell, DataTableColumn, DataTableColumnHeader } from '@/components/ui/data-table'
import { localModel } from '@virtuoso.dev/data-table'

const rows = [
  { id: 'SKU-001', name: 'Standing Desk', category: 'Office', stock: 14 },
  { id: 'SKU-002', name: 'USB-C Dock', category: 'Peripherals', stock: 42 },
  { id: 'SKU-003', name: 'Mechanical Keyboard', category: 'Peripherals', stock: 28 },
]

const model = localModel({ data: rows })

export default function App() {
  return (
    <DataTable className="rounded-xl" model={model} style={{ height: 260 }}>
      <DataTableColumn field="name">
        <DataTableColumnHeader>Product</DataTableColumnHeader>
        <DataTableCell className="font-medium">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="category" />
      <DataTableColumn field="stock">
        <DataTableColumnHeader className="justify-end">Stock</DataTableHeader>
        <DataTableCell className="text-right tabular-nums">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
    </DataTable>
  )
}
```

--------------------------------

### Quick Start with Virtuoso Masonry

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/masonry/README.md

A basic example demonstrating how to use VirtuosoMasonry with a fixed column count and a dataset of 1000 items.

```tsx
import { VirtuosoMasonry } from '@virtuoso.dev/masonry'
import { useMemo } from 'react'

const ItemContent: React.FC<{ data: number }> = ({ data }) => {
  const height = data % 10 === 0 ? 200 : data % 5 === 0 ? 180 : data % 7 ? 150 : 120
  return (
    <div style={{ padding: '5px' }}>
      <div style={{ height, border: '1px solid black' }}>Item {data}</div>
    </div>
  )
}

export default function App() {
  const data = useMemo(() => {
    return Array.from({ length: 1000 }, (_, index) => index)
  }, [])

  return (
    <div>
      <VirtuosoMasonry columnCount={3} data={data} style={{ height: 500 }} initialItemCount={50} ItemContent={ItemContent} />
    </div>
  )
}
```

--------------------------------

### Minimal Setup for State Persistence

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/data-table/docs/5.state-persistence.md

This example demonstrates the basic setup for state persistence in a DataTable. It includes adapters for column visibility and width, and a custom ColumnPicker component to toggle column visibility. The state is saved using a specified storage key.

```tsx
import { DataTable, DataTableCell, DataTableColumn, DataTableColumnHeader, HeaderEdge } from '@/components/ui/data-table'
import { ResizeHandle } from '@/components/ui/data-table/column-resize'
import { columns$, localModel, useCellValue, usePublisher } from '@virtuoso.dev/data-table'
import { columnWidthPersistenceAdapter } from '@virtuoso.dev/data-table/column-resize'
import {
  columnVisibilityPersistenceAdapter,
  columnVisibilityState$,
  setColumnVisibility$,
} from '@virtuoso.dev/data-table/column-visibility'
import { DataTableStatePersistence } from '@virtuoso.dev/data-table/state-persistence'

const rows = [
  { id: 'SKU-001', product: 'Standing Desk', category: 'Office', stock: 14, internalId: 'inv-001' },
  { id: 'SKU-002', product: 'USB-C Dock', category: 'Peripherals', stock: 42, internalId: 'inv-002' },
  { id: 'SKU-003', product: 'Mechanical Keyboard', category: 'Peripherals', stock: 28, internalId: 'inv-003' },
  { id: 'SKU-004', product: 'Noise-canceling Headset', category: 'Audio', stock: 9, internalId: 'inv-004' },
]

const model = localModel({ data: rows })
const adapters = [columnVisibilityPersistenceAdapter(), columnWidthPersistenceAdapter()]

function ColumnPicker() {
  const columns = useCellValue(columns$)
  const visibility = useCellValue(columnVisibilityState$)
  const setColumnVisibility = usePublisher(setColumnVisibility$)

  return (
    <div className="mb-3 flex flex-wrap gap-2 rounded-md border bg-muted/30 p-3 text-sm">
      {[...columns].map(([key, column]) => {
        const visible = visibility.get(key) ?? column.visible !== false
        return (
          <button
            aria-pressed={visible}
            className={visible ? 'rounded border bg-background px-2 py-1 font-medium' : 'rounded border px-2 py-1 text-muted-foreground'}
            key={key}
            onClick={() => setColumnVisibility({ key, visible: !visible })}
            type="button"
          >
            {visible ? 'Hide' : 'Show'} {column.field}
          </button>
        )
      })}
    </div>
  )
}

export default function App() {
  return (
    <DataTable className="rounded-xl" computeRowKey={({ data }) => data.id} model={model} style={{ height: 360 }}>
      <DataTableStatePersistence adapters={adapters} storageKey="docs-state-persistence-feature-page" />
      <ColumnPicker />

      <DataTableColumn field="product">
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Product'}
        </DataTableColumnHeader>
        <DataTableCell className="font-medium">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="category">
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Category'}
        </DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="stock">
        <DataTableColumnHeader className="justify-end">
          <HeaderEdge component={ResizeHandle} />
          {() => 'Stock'}
        </DataTableColumnHeader>
        <DataTableCell className="text-right tabular-nums">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="internalId" visible={false}>
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Internal ID'}
        </DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
    </DataTable>
  )
}

```

--------------------------------

### Minimal DataTable State Persistence Setup

Source: https://github.com/petyosi/react-virtuoso/blob/main/plugins/virtuoso-skills/skills/data-table/references/5.state-persistence.md

This example demonstrates the basic setup for state persistence in a data table. It includes column visibility and width persistence adapters. Ensure the component is mounted inside the DataTable and the storageKey is unique for each table instance.

```tsx
import {
  DataTable,
  DataTableCell,
  DataTableColumn,
  DataTableColumnHeader,
  HeaderEdge,
} from '@/components/ui/data-table'
import { ResizeHandle } from '@/components/ui/data-table/column-resize'
import {
  columns$,
  localModel,
  useCellValue,
  usePublisher,
} from '@virtuoso.dev/data-table'
import {
  columnWidthPersistenceAdapter,
} from '@virtuoso.dev/data-table/column-resize'
import {
  columnVisibilityPersistenceAdapter,
  columnVisibilityState$,
  setColumnVisibility$,
} from '@virtuoso.dev/data-table/column-visibility'
import { DataTableStatePersistence } from '@virtuoso.dev/data-table/state-persistence'

const rows = [
  { id: 'SKU-001', product: 'Standing Desk', category: 'Office', stock: 14, internalId: 'inv-001' },
  { id: 'SKU-002', product: 'USB-C Dock', category: 'Peripherals', stock: 42, internalId: 'inv-002' },
  { id: 'SKU-003', product: 'Mechanical Keyboard', category: 'Peripherals', stock: 28, internalId: 'inv-003' },
  { id: 'SKU-004', product: 'Noise-canceling Headset', category: 'Audio', stock: 9, internalId: 'inv-004' },
]

const model = localModel({ data: rows })
const adapters = [
  columnVisibilityPersistenceAdapter(),
  columnWidthPersistenceAdapter(),
]

function ColumnPicker() {
  const columns = useCellValue(columns$)
  const visibility = useCellValue(columnVisibilityState$)
  const setColumnVisibility = usePublisher(setColumnVisibility$)

  return (
    <div className="mb-3 flex flex-wrap gap-2 rounded-md border bg-muted/30 p-3 text-sm">
      {[...columns].map(([key, column]) => {
        const visible = visibility.get(key) ?? column.visible !== false
        return (
          <button
            aria-pressed={visible}
            className={visible ? 'rounded border bg-background px-2 py-1 font-medium' : 'rounded border px-2 py-1 text-muted-foreground'}
            key={key}
            onClick={() => setColumnVisibility({ key, visible: !visible })}
            type="button"
          >
            {visible ? 'Hide' : 'Show'} {column.field}
          </button>
        )
      })}
    </div>
  )
}

export default function App() {
  return (
    <DataTable className="rounded-xl" computeRowKey={({ data }) => data.id} model={model} style={{ height: 360 }}>
      <DataTableStatePersistence adapters={adapters} storageKey="docs-state-persistence-feature-page" />
      <ColumnPicker />

      <DataTableColumn field="product">
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Product'}
        </DataTableColumnHeader>
        <DataTableCell className="font-medium">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="category">
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Category'}
        </DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="stock">
        <DataTableColumnHeader className="justify-end">
          <HeaderEdge component={ResizeHandle} />
          {() => 'Stock'}
        </DataTableColumnHeader>
        <DataTableCell className="text-right tabular-nums">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="internalId" visible={false}>
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Internal ID'}
        </DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
    </DataTable>
  )
}

```

--------------------------------

### Quick Start with VirtuosoMessageList

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/message-list/README.md

Basic setup for VirtuosoMessageList, including license key, data preparation, and rendering a list of messages. Ensure to replace 'your-license-key' with your actual license.

```tsx
import { VirtuosoMessageListLicense, VirtuosoMessageList, VirtuosoMessageListProps } from '@virtuoso.dev/message-list'
import { useMemo } from 'react'

const licenseKey = 'your-license-key'

export default function App() {
  const data = useMemo<VirtuosoMessageListProps<{ id: number; content: string }, null>['data']>(() => {
    return {
      data: Array.from({ length: 100 }, (_, index) => ({ id: index, content: `Message ${index}` })),
      scrollModifier: {
        type: 'item-location',
        location: {
          index: 'LAST',
          align: 'end',
        },
      },
    }
  }, [])

  return (
    <VirtuosoMessageListLicense licenseKey={licenseKey}>
      <VirtuosoMessageList style={{ height: '100%' }} data={data} ItemContent={({ data }) => <div>{data.content}</div>} />
    </VirtuosoMessageListLicense>
  )
}
```

--------------------------------

### Develop Examples with Ladle

Source: https://github.com/petyosi/react-virtuoso/blob/main/CLAUDE.md

Launch the Ladle development server to browse and develop examples for the react-virtuoso package.

```bash
pnpm run ladle
```

--------------------------------

### Start Docs Site

Source: https://github.com/petyosi/react-virtuoso/blob/main/AGENTS.md

Start the documentation site locally. This command is used to preview the documentation as it would appear online.

```bash
pnpm dev:docs
```

--------------------------------

### Minimal Setup for State Persistence

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/virtuoso-skills/skills/data-table/references/5.state-persistence.md

This example demonstrates the minimal setup for state persistence in a data table. It includes column visibility and width persistence adapters. Ensure the DataTableStatePersistence component is mounted inside the DataTable and adapters are passed for the features you want to persist.

```tsx
import { DataTable, DataTableCell, DataTableColumn, DataTableColumnHeader, HeaderEdge } from '@/components/ui/data-table'
import { ResizeHandle } from '@/components/ui/data-table/column-resize'
import { columns$, localModel, useCellValue, usePublisher } from '@virtuoso.dev/data-table'
import { columnWidthPersistenceAdapter } from '@virtuoso.dev/data-table/column-resize'
import {
  columnVisibilityPersistenceAdapter,
  columnVisibilityState$,
  setColumnVisibility$,
} from '@virtuoso.dev/data-table/column-visibility'
import { DataTableStatePersistence } from '@virtuoso.dev/data-table/state-persistence'

const rows = [
  { id: 'SKU-001', product: 'Standing Desk', category: 'Office', stock: 14, internalId: 'inv-001' },
  { id: 'SKU-002', product: 'USB-C Dock', category: 'Peripherals', stock: 42, internalId: 'inv-002' },
  { id: 'SKU-003', product: 'Mechanical Keyboard', category: 'Peripherals', stock: 28, internalId: 'inv-003' },
  { id: 'SKU-004', product: 'Noise-canceling Headset', category: 'Audio', stock: 9, internalId: 'inv-004' },
]

const model = localModel({ data: rows })
const adapters = [columnVisibilityPersistenceAdapter(), columnWidthPersistenceAdapter()]

function ColumnPicker() {
  const columns = useCellValue(columns$)
  const visibility = useCellValue(columnVisibilityState$)
  const setColumnVisibility = usePublisher(setColumnVisibility$)

  return (
    <div className="mb-3 flex flex-wrap gap-2 rounded-md border bg-muted/30 p-3 text-sm">
      {[...columns].map(([key, column]) => {
        const visible = visibility.get(key) ?? column.visible !== false
        return (
          <button
            aria-pressed={visible}
            className={visible ? 'rounded border bg-background px-2 py-1 font-medium' : 'rounded border px-2 py-1 text-muted-foreground'}
            key={key}
            onClick={() => setColumnVisibility({ key, visible: !visible })}
            type="button"
          >
            {visible ? 'Hide' : 'Show'} {column.field}
          </button>
        )
      })}
    </div>
  )
}

export default function App() {
  return (
    <DataTable className="rounded-xl" computeRowKey={({ data }) => data.id} model={model} style={{ height: 360 }}>
      <DataTableStatePersistence adapters={adapters} storageKey="docs-state-persistence-feature-page" />
      <ColumnPicker />

      <DataTableColumn field="product">
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Product'}
        </DataTableColumnHeader>
        <DataTableCell className="font-medium">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="category">
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Category'}
        </DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="stock">
        <DataTableColumnHeader className="justify-end">
          <HeaderEdge component={ResizeHandle} />
          {() => 'Stock'}
        </DataTableColumnHeader>
        <DataTableCell className="text-right tabular-nums">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="internalId" visible={false}>
        <DataTableColumnHeader>
          <HeaderEdge component={ResizeHandle} />
          {() => 'Internal ID'}
        </DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
    </DataTable>
  )
}
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/petyosi/react-virtuoso/blob/main/apps/virtuoso.dev/README.md

Run this command in the root of your project to install all necessary dependencies defined in package.json.

```bash
pnpm install
```

--------------------------------

### Install Reactive Engine Core and React Bindings

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/reactive-engine-react/README.md

Install the core reactive engine and its React bindings using npm.

```bash
npm install @virtuoso.dev/reactive-engine-core @virtuoso.dev/reactive-engine-react
```

--------------------------------

### Install Reactive Engine Packages

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/reactive-engine-router/README.md

Install the core, react, and router packages for the reactive engine.

```bash
npm install @virtuoso.dev/reactive-engine-core @virtuoso.dev/reactive-engine-react @virtuoso.dev/reactive-engine-router
```

--------------------------------

### Install Reactive Engine Query

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/reactive-engine-query/README.md

Install the core and query packages for reactive engine.

```bash
npm install @virtuoso.dev/reactive-engine-core @virtuoso.dev/reactive-engine-query
```

--------------------------------

### App Component Setup with DataTable and ControlPanel

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/virtuoso-skills/skills/data-table/references/8.examples/10.table-instance-dashboard.md

Sets up the main application component, integrating the `DataTable` with an external `ControlPanel`. It uses `useEngineRef` to link the two components and defines the table columns and data structure. This snippet is the main entry point for the example.

```tsx
import { DataTable, DataTableCell, DataTableColumn, DataTableColumnHeader } from '@/components/ui/data-table'
import { localModel, useEngineRef } from '@virtuoso.dev/data-table'

import { ControlPanel } from './ControlPanel'
import { products } from './data'

const model = localModel({ data: products })

export default function App() {
  const engineRef = useEngineRef()

  return (
    <div className="grid gap-4 lg:grid-cols-[280px_minmax(0,1fr)]">
      <ControlPanel engineRef={engineRef} />

      <DataTable className="rounded-xl" model={model} engineRef={engineRef} style={{ height: 420 }}>
        <DataTableColumn field="name">
          <DataTableColumnHeader>Product</DataTableColumnHeader>
          <DataTableCell className="font-medium">{({ row }) => row.data.name}</DataTableCell>
        </DataTableColumn>
        <DataTableColumn field="category">
          <DataTableColumnHeader>Category</DataTableColumnHeader>
          <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
        </DataTableColumn>
        <DataTableColumn field="status">
          <DataTableColumnHeader>Status</DataTableColumnHeader>
          <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
        </DataTableColumn>
        <DataTableColumn field="region">
          <DataTableColumnHeader>Region</DataTableHeader>
          <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
        </DataTableColumn>
      </DataTable>
    </div>
  )
}
```

--------------------------------

### Start Local Development Server

Source: https://github.com/petyosi/react-virtuoso/blob/main/apps/virtuoso.dev/README.md

This command starts a local development server, typically accessible at localhost:4321, allowing you to preview your site during development.

```bash
pnpm dev
```

--------------------------------

### Install All Agent Skills (CLI)

Source: https://github.com/petyosi/react-virtuoso/blob/main/apps/virtuoso.dev/src/content/docs/skills.mdx

Install all available agent skills from the virtuoso-dev/skills repository using the Agent Skills CLI.

```bash
npx skills add virtuoso-dev/skills --skill '*'
```

--------------------------------

### Basic Data Table with Shadcn UI

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/data-table/README.md

Demonstrates a basic implementation of a virtualized data table using the shadcn-style wrapper. It includes setup for local data, defining columns with headers and cells, and applying basic styling. Use this for a quick start with a polished table appearance.

```tsx
import { DataTable, DataTableCell, DataTableColumn, DataTableColumnHeader } from '@/components/ui/data-table'
import { localModel } from '@virtuoso.dev/data-table'

const products = [
  { id: 'SKU-001', name: 'Standing Desk', category: 'Office', price: 699, stock: 14 },
  { id: 'SKU-002', name: 'USB-C Dock', category: 'Peripherals', price: 229, stock: 42 },
  { id: 'SKU-003', name: 'Mechanical Keyboard', category: 'Peripherals', price: 169, stock: 28 },
  { id: 'SKU-004', name: 'Noise-canceling Headset', category: 'Audio', price: 319, stock: 9 },
]

const currency = new Intl.NumberFormat('en-US', {
  currency: 'USD',
  style: 'currency',
})

const model = localModel({ data: products })

export default function App() {
  return (
    <DataTable className="rounded-xl" model={model} style={{ height: 320 }}>
      <DataTableColumn field="name">
        <DataTableColumnHeader>Name</DataTableColumnHeader>
        <DataTableCell className="font-medium">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="category">
        <DataTableColumnHeader>Category</DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="price">
        <DataTableColumnHeader className="justify-end">Price</DataTableColumnHeader>
        <DataTableCell className="text-right tabular-nums">{({ cellValue }) => currency.format(Number(cellValue))}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="stock">
        <DataTableColumnHeader className="justify-end">Stock</DataTableColumnHeader>
        <DataTableCell className="text-right tabular-nums">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
    </DataTable>
  )
}
```

--------------------------------

### Install Reactive Engine Core and Storage

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/reactive-engine-storage/README.md

Install the necessary packages for reactive engine core and storage persistence.

```bash
npm install @virtuoso.dev/reactive-engine-core @virtuoso.dev/reactive-engine-storage
```

--------------------------------

### Install React Virtuoso

Source: https://github.com/petyosi/react-virtuoso/blob/main/README.md

Install the react-virtuoso package using npm.

```sh
npm install react-virtuoso
```

--------------------------------

### Basic Local Model Setup

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/data-table/docs/2.data-model/index.md

Use a local model for in-memory rows. Keep the model stable and pass it to DataTable with model={model}. This example demonstrates setting up a local model with sample product data and rendering it in a DataTable.

```tsx
import { DataTable, DataTableCell, DataTableColumn, DataTableColumnHeader } from '@/components/ui/data-table'
import { localModel } from '@virtuoso.dev/data-table'

const rows = [
  { id: 'SKU-001', name: 'Standing Desk', category: 'Office', stock: 14 },
  { id: 'SKU-002', name: 'USB-C Dock', category: 'Peripherals', stock: 42 },
  { id: 'SKU-003', name: 'Mechanical Keyboard', category: 'Peripherals', stock: 28 },
]

const model = localModel({ data: rows })

export default function App() {
  return (
    <DataTable className="rounded-xl" model={model} style={{ height: 280 }}>
      <DataTableColumn field="name">
        <DataTableColumnHeader>Product</DataTableColumnHeader>
        <DataTableCell className="font-medium">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="category">
        <DataTableColumnHeader>Category</DataTableColumnHeader>
        <DataTableCell>{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
      <DataTableColumn field="stock">
        <DataTableColumnHeader className="justify-end">Stock</DataTableColumnHeader>
        <DataTableCell className="text-right tabular-nums">{({ cellValue }) => String(cellValue)}</DataTableCell>
      </DataTableColumn>
    </DataTable>
  )
}
```

--------------------------------

### Install Reactive Engine Core

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/reactive-engine-core/README.md

Install the core package using npm.

```bash
npm install @virtuoso.dev/reactive-engine-core
```

--------------------------------

### Quick Example: Setting up a Reactive Router

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/reactive-engine-router/README.md

Demonstrates setting up a root layout and defining navigation buttons using usePublisher for route navigation. Ensure route definitions like home$ and about$ are imported.

```tsx
import { usePublisher } from '@virtuoso.dev/reactive-engine-react'
import { Layout, Router } from '@virtuoso.dev/reactive-engine-router'

import { about$, home$ } from './routes'

const rootLayout = Layout('/', ({ children }) => (
  <div>
    <Navigation />
    <main>{children}</main>
  </div>
))

function Navigation() {
  const goHome = usePublisher(home$)
  const goToAbout = usePublisher(about$)

  return (
    <nav>
      <button onClick={() => goHome({})}>Home</button>
      <button onClick={() => goToAbout({})}>About</button>
    </nav>
  )
}

export function App() {
  return <Router layouts={[rootLayout]} routes={[home$, about$]} />
}
```

--------------------------------

### GroupedVirtuoso Example with First Letter Grouping

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/react-virtuoso/docs/2.grouped-virtuoso/grouped-by-first-letter.md

Use GroupedVirtuoso to display a list of users grouped by the first letter of their name. This example generates dummy user data and group information. Ensure you have react-virtuoso installed.

```tsx
import { GroupedVirtuoso } from 'react-virtuoso'
import { useMemo } from 'react'

export default function App() {
  const { users, groups, groupCounts } = useMemo(() => {
    const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('')

    const users = letters.flatMap((letter) => {
      return Array.from({ length: 20 }, (_, index) => ({
        name: `${letter} User ${index}`,
        initials: `${letter}${index}`,
        description: `Description for user ${index}`,
      }))
    })

    const groups = Array.from({ length: 10 }, (_, index) => {
      return letters[index]
    })

    const groupCounts = groups.map((letter, index) => {
      return users.filter((user, userIndex) => user.name.startsWith(letter)).length
    })
    return { users, groups, groupCounts }
  }, [])

  return (
    <GroupedVirtuoso
      groupCounts={groupCounts}
      style={{ height: '100%' }}
      groupContent={(index) => {
        return (
          <div
            style={{
              backgroundColor: 'var(--background)',
              paddingTop: '1rem',
              borderBottom: '1px solid var(--border)',
            }}
          >
            {groups[index]}
          </div>
        )
      }}
      itemContent={(index) => {
        return <div>{users[index].name}</div>
      }}
    />
  )
}
```

--------------------------------

### Run Documentation Site Development Server

Source: https://github.com/petyosi/react-virtuoso/blob/main/CONTRIBUTING.md

Starts the development server for the Starlight/Astro documentation site. Navigate to the documentation app directory first.

```bash
cd apps/virtuoso.dev
pnpm run dev
```

--------------------------------

### Run Dev Server for virtuoso.dev Docs App

Source: https://github.com/petyosi/react-virtuoso/blob/main/CLAUDE.md

Start the development server for the virtuoso.dev documentation site. Run this command from the 'apps/virtuoso.dev/' directory.

```bash
pnpm run dev
```

--------------------------------

### Integrate SimpleBar with VirtuosoMessageList

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/message-list/docs/8.custom-scrollbar.md

This example shows how to use SimpleBar with VirtuosoMessageList. Ensure SimpleBar is installed and its CSS is imported. The scrollable node ref from SimpleBar is passed to VirtuosoMessageList via the customScrollParent prop.

```tsx
import { VirtuosoMessageListLicense, VirtuosoMessageList } from '@virtuoso.dev/message-list'
import SimpleBar from 'simplebar-react'
import 'simplebar-react/dist/simplebar.min.css'
import { useState } from 'react'

export default function App() {
  const [scrollParent, setScrollParent] = useState<HTMLDivElement | null>(null)
  return (
    <VirtuosoMessageListLicense licenseKey="">
      <SimpleBar style={{ height: 300 }} scrollableNodeProps={{ ref: setScrollParent }}>
        {scrollParent && (
          <VirtuosoMessageList customScrollParent={scrollParent} data={{ data: Array.from({ length: 100 }, (_, index) => index) }} />
        )}
      </SimpleBar>
    </VirtuosoMessageListLicense>
  )
}
```

--------------------------------

### Remove Range of Items

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/message-list/docs/15.imperative-data-api.md

Utilize the `useRef` hook to get a reference to the `VirtuosoMessageListMethods` and then call `ref.current.data.deleteRange` to remove multiple items efficiently. This method takes a starting index and the number of items to delete.

```tsx
import { VirtuosoMessageList, useVirtuosoMethods, VirtuosoMessageListLicense, VirtuosoMessageListMethods } from '@virtuoso.dev/message-list'
import { useRef } from 'react'

function ItemContent({ data }) {
  return <div>Item {data}</div>
}

export default function App() {
  const ref = useRef<VirtuosoMessageListMethods>(null)
  return (
    <>
      <button onClick={() => ref.current.data.deleteRange(5, 10)}>Remove 10 items starting from 5</button>
      <VirtuosoMessageListLicense licenseKey="">
        <VirtuosoMessageList
          ref={ref}
          ItemContent={ItemContent}
          style={{ height: 500 }}
          initialData={Array.from({ length: 100 }, (_, index) => index)}
        />
      </VirtuosoMessageListLicense>
    </>
  )
}
```

--------------------------------

### React Virtuoso Range Change Callback Example

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/react-virtuoso/docs/1.virtuoso/range-change-callback.md

Demonstrates how to use the `rangeChanged` callback to track the visible item range in a React Virtuoso list. The callback updates a state variable with the start and end indexes of the visible items.

```tsx
import { Virtuoso } from 'react-virtuoso'
import { useState } from 'react'

export default function App() {
  const [visibleRange, setVisibleRange] = useState({
    startIndex: 0,
    endIndex: 0,
  })
  return (
    <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
      <p>
        current visible range: {visibleRange.startIndex} - {visibleRange.endIndex}{' '}
      </p>
      <Virtuoso totalCount={1000} rangeChanged={setVisibleRange} style={{ flex: 1 }} itemContent={(index) => <div>Item {index}</div>} />
    </div>
  )
}
```

--------------------------------

### Create Astro Project with Starlight Template

Source: https://github.com/petyosi/react-virtuoso/blob/main/apps/virtuoso.dev/README.md

Use this command to initialize a new Astro project with the Starlight template. Ensure you have pnpm installed.

```bash
pnpm create astro@latest -- --template starlight
```

--------------------------------

### Initialize and Use Reactive Engine

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/virtuoso-skills/skills/reactive-engine/SKILL.md

Demonstrates how to import necessary components, create a Cell node, initialize an Engine, subscribe to the Cell's value changes, and publish a new value to it.

```typescript
import { Cell, Stream, Engine, e } from '@virtuoso.dev/reactive-engine-core'

const count$ = Cell(0)
const engine = new Engine()
engine.sub(count$, (value) => console.log('count:', value))
engine.pub(count$, 1) // logs 'count: 1'
```

--------------------------------

### Scroll to Specific Index with Options

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/react-virtuoso/docs/1.virtuoso/scroll-to-index.md

This example demonstrates how to use the scrollToIndex method to navigate to specific items (1, 500, 1000) within the Virtuoso component. It allows users to select alignment ('start', 'center', 'end') and scrolling behavior ('auto', 'smooth') for the scroll action. Use this when you need to programmatically control the scroll position based on user interaction or application logic.

```tsx
import { Virtuoso } from 'react-virtuoso'
import { useState, useRef } from 'react'

export default function App() {
  const [align, setAlign] = useState('start')
  const [behavior, setBehavior] = useState('auto')
  const virtuoso = useRef(null)
  return (
    <div>
      <ul style={{ listStyle: 'none', display: 'flex', flexDirection: 'row', gap: 5, alignItems: 'baseline', flexWrap: 'wrap' }}>
        <li>
          <button
            style={{ whiteSpace: 'nowrap' }}
            onClick={() => {
              virtuoso.current.scrollToIndex({
                index: 0,
                align,
                behavior,
              })
              return false
            }}
          >
            Go to 1
          </button>
        </li>
        <li>
          <button
            style={{ whiteSpace: 'nowrap' }}
            onClick={() => {
              virtuoso.current.scrollToIndex({
                index: 499,
                align,
                behavior,
              })
              return false
            }}
          >
            Go to 500
          </button>
        </li>
        <li>
          <button
            style={{ whiteSpace: 'nowrap' }}
            onClick={() => {
              virtuoso.current.scrollToIndex({
                index: 999,
                align,
                behavior,
              })
              return false
            }}
          >
            Go to 1000
          </button>
        </li>
        <li>
          <label>
            Align:
            <select value={align} onChange={(e) => setAlign(e.target.value)}>
              <option value="start">Start</option>
              <option value="center">Center</option>
              <option value="end">End</option>
            </select>
          </label>
        </li>
        <li>
          <label>
            Behavior:
            <select value={behavior} onChange={(e) => setBehavior(e.target.value)}>
              <option value="auto">Instant (auto)</option>
              <option value="smooth">Smooth</option>
            </select>
          </label>
        </li>
      </ul>

      <div style={{ height: 300 }}>
        <Virtuoso totalCount={1000} ref={virtuoso} itemContent={(index) => <div style={{ height: 30 }}>Item {index + 1}</div>} />
      </div>
    </div>
  )
}
```

--------------------------------

### Install Virtuoso Masonry

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/masonry/README.md

Install the Virtuoso Masonry package using npm.

```bash
npm install @virtuoso.dev/masonry
```

--------------------------------

### Install Virtuoso Skills for Agent Skills Users

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/virtuoso-skills/README.md

Install skills from the dedicated public mirror using npx skills. This method pulls only the necessary skill directories.

```bash
npx skills add virtuoso-dev/skills --skill '*' -a codex -a opencode -a cursor --copy -y
```

--------------------------------

### Install Virtuoso Message List

Source: https://github.com/petyosi/react-virtuoso/blob/main/packages/message-list/README.md

Install the Virtuoso Message List package using npm.

```bash
npm install @virtuoso.dev/message-list
```