vue-cerious-scroll

KO | EN

gitlite — search

#web #codex #chatbot #html #terminal #python #openai #kotlin #graphql #cloud-native

vue-cerious-scroll

(★ 9)

Vue implementation for Cerious-Scroll

File Explorer

ZIP Download

- - deploy-pages.yml
  - publish.yml
- - analytics.ts
  - app.css
  - App.vue
  - env.d.ts
  - FpsMeter.vue
  - Gallery.vue
  - Layout.vue
  - main.ts
  - registry.ts
  - router.ts
- index.html
- tsconfig.json
- vite.config.ts
- ARCHITECTURE.md
- IMPLEMENTATION_GUIDE.md
- cerious-scroll.ts
- content-element.ts
- index.ts
- use-cerious-scroll.ts
- viewport-change.ts
- cerious-scroll.test.ts
- setup.ts
.gitignore
CHANGELOG.md
LICENSE
LICENSE-MIT
package-lock.json
package.json
README.md
tsconfig.json
vite.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

License Visit
Live Demo Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Vue 3 bindings for [Cerious Scroll™](https://www.npmjs.com/package/@ceriousdevtech/cerious-scroll)** — high-performance virtual scrolling with **O(1) memory**, consistent **60 FPS+**, and **native variable-height support with no height estimation**.

Rows are rendered into the engine's own measured containers via Vue's synchronous `render()`, so every row's real height is measured (never estimated) — exactly the guarantee that makes CeriousScroll precise. Rows are rendered with your app's `appContext`, so **globally registered components, directives, and installed plugins work normally** inside each row.

---

## Installation

```bash
npm install @ceriousdevtech/vue-cerious-scroll @ceriousdevtech/cerious-scroll
```

`vue` (>= 3.3) is a peer dependency.

---

## Demo

**[Live demo →](https://ceriousdevtech.github.io/vue-cerious-scroll/)** — 100,000 rows, fixed/variable-height toggle, imperative jump-to-row, and live viewport stats.

To run locally:

```bash
npm install
npm run demo        # dev server with HMR
npm run demo:build  # production build to demo/dist
```

The demo imports the wrapper by its package name, aliased to the library source,
so edits to `src/` are reflected live.

---

## Quick start (component)

Give the container a height; provide `items` and an `#item` scoped slot.

```vue
<script setup lang="ts">
import { CeriousScroll } from '@ceriousdevtech/vue-cerious-scroll';

const items = Array.from({ length: 1_000_000 }, (_, i) => ({ id: i, name: `Item ${i}` }));
</script>

<template>
  <CeriousScroll :items="items" :style="{ height: '480px' }">
    <template #item="{ item, index }">
      <div class="row">{{ index }} — {{ item.name }}</div>
    </template>
  </CeriousScroll>
</template>
```

Variable heights need no configuration — just render rows of whatever height; the
engine measures each one.

### Without a full array (huge / sparse data)

```vue
<CeriousScroll
  :total-elements="100_000_000"
  :get-item="(index) => loadRow(index)"
  :style="{ height: '600px' }"
>
  <template #item="{ item, index }">
    <Row :data="item" :index="index" />
  </template>
</CeriousScroll>
```

---

## Composable

`useCeriousScroll` gives you full control. Attach `containerRef` to your scroll
element; the composable renders the rows imperatively into the engine's measured
containers.

```vue
<script setup lang="ts">
import { h } from 'vue';
import { useCeriousScroll } from '@ceriousdevtech/vue-cerious-scroll';

const { containerRef } = useCeriousScroll({
  items,
  renderItem: (item, index) => h('div', { class: 'row' }, `${index} — ${item.name}`),
});
</script>

<template>
  <div ref="containerRef" style="height: 480px; position: relative; overflow: hidden" />
</template>
```

> `renderItem` returns a Vue `VNodeChild` (use `h(...)`, or render JSX/TSX).

---

## Component props

| Prop | Type | Description |
| --- | --- | --- |
| `items` | `readonly TItem[]` | Optional data array. `totalElements` defaults to `items.length`. |
| `totalElements` | `number` | Total item count. Required if `items` is omitted. |
| `getItem` | `(index) => TItem` | Lazy item getter for large/sparse datasets. |
| `renderItem` | `(item, index) => VNodeChild` | Render prop alternative to the `#item` scoped slot. |
| `options` | `CeriousScrollOptions` | Engine options. Masonry's DOM callback is supplied by the wrapper. Read once at creation. |
| `autoRender` | `boolean` | Re-render on scroll/resize/data changes. Default `true`. |

The row is provided by the **`#item` scoped slot** (`{ item, index }`) or the
`render-item` prop. In table mode, a **`#header` slot** renders the `<thead>` row
(see [Table layout](#table-layout)). Apply `class` / `style` directly to the
component — they fall through onto the scroll container (set a height!).

### Events

| Event | Payload | Description |
| --- | --- | --- |
| `viewport-change` | `CeriousViewportChangeDetail` | Normalized viewport-change (wheel/touch/keyboard/scrollbar). |
| `measured-viewport` | `MeasuredViewportRange` | Measured range after each render pass. |
| `ready` | `CeriousScrollEngine` | The underlying engine instance, once ready. |

### Imperative API (via template `ref`)

```ts
const scroll = ref<InstanceType<typeof CeriousScroll> | null>(null);
// scroll.value?.jumpToElement(500);
// scroll.value?.jumpToItem(500); // Masonry cards
// scroll.value?.scrollToPercentage(50);
// scroll.value?.reset();
// scroll.value?.render();
// scroll.value?.recalculate(); // drop cached heights + re-measure (see Notes)
// scroll.value?.scroller;      // the raw engine
```

---

## Masonry layout

Set `layout: 'masonry'`; the wrapper renders the `#item` slot into each core
Masonry card, so no imperative DOM callback is exposed:

```vue
<CeriousScroll
  ref="scroll"
  class="gallery"
  :total-elements="photos.length"
  :get-item="(index) => photos[index]"
  :options="{
    layout: 'masonry',
    masonry: {
      getItemHeight: (_index, width) => width * 0.75 + 48,
      targetColumnWidth: 280,
      gap: 16
    }
  }"
>
  <template #item="{ item: photo, index }">
    <PhotoCard :photo="photo" :index="index" />
  </template>
</CeriousScroll>
```

Omit `getItemHeight` for dynamic DOM measurement. Vue creates a short-lived
offscreen render tree for measurement and disposes it after the synchronous
height read; visible cards remain reactive Vue trees with provide/inject and
event handling.

Use `scroll.value?.jumpToItem(index, screenOffset?)` for card navigation. The
demo gallery includes canonical and dynamic Masonry pages.

## Table layout

Pass `:options="{ layout: 'table' }"` to render real `<table>` / `<tr>` / `<td>` rows with a frozen header and native column alignment. The `#item` slot returns the row's `<td>` cells; a `#header` slot provides the (declarative, reactive) `<thead>` row:

```vue
<CeriousScroll
  class="my-scroll"
  :total-elements="100000"
  :get-item="(i) => i"
  :options="{ layout: 'table', table: { tableClassName: 'my-table', autoSizeColumns: true } }"
>
  <template #header>
    <tr><th v-for="c in columns" :key="c.key">{{ c.label }}</th></tr>
  </template>

<template #item="{ item: index }">
    <td>{{ row(index).id }}</td>
    <td>{{ row(index).name }}</td>
    <td>{{ row(index).email }}</td>
  </template>
</CeriousScroll>
```

- The **`#header` slot** renders into the engine's `<thead>` (same `<table>` as the rows → native column alignment, frozen header) and stays reactive.
- The **`#item` slot must return `<td>`s**. They render into the row's `<tr>` via a `display: contents` wrapper that isolates Vue's renderer from the engine's row recycling.
- **`table.autoSizeColumns`** measures column widths once and pins them (auto-sized + stable); or use `table.columnWidths`. Variable row heights work as usual.
- CSS: `border-collapse: separate` and an **opaque `<thead>` background** (see the core README's [Table Layout](https://github.com/ceriousdevtech/cerious-scroll#-table-layout-layout-table) notes).

---

## Notes

- **No height estimation.** Rows are committed with Vue's synchronous `render()`
  so the engine measures real `offsetHeight`. Later size changes are picked up by
  the engine's built-in `ResizeObserver`.
- **`options` are read at creation.** Changing `options` after mount has no
  effect; remount (e.g. with a `:key`) to apply new engine options.
- **Changing the item count** updates lists/tables in place. Masonry recreates
  its card-count-derived segment layout. Mutating items without changing the count just re-renders the
  content in place (cheap; Vue patches each row, so focus/selection survive) — it
  does **not** discard cached heights, so editable grids that produce a new
  `items` array on every edit don't trigger a full viewport re-measure.
- **If every rendered row's height changes at once** (e.g. a density/layout
  switch) the cached heights become stale and rows can misalign until the next
  scroll. Call `recalculate()` (on the template `ref`, or from the composable
  result) right after the change to drop the height cache and re-measure. Don't
  call it on routine edits — a single cell edit keeps its row's size, and the
  engine's built-in `ResizeObserver` picks up any incidental resize on its own.

---

## License

Licensed by **Cerious DevTech LLC** under the **MIT License** (see `LICENSE-MIT`).

📧 info@ceriousdevtech.com

vue-cerious-scroll

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

vue-cerious-scroll

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README