feat(lit-virtual): add setOptions to update virtualizer options after construction by itisrmk · Pull Request #1334 · TanStack/virtual

itisrmk · 2026-10-20T08:26:29Z

🎯 Changes

VirtualizerController only took options in its constructor, so options that come from reactive Lit properties (count, estimateSize, horizontal, and so on) never reached the virtualizer after the first render. Calling getVirtualizer().setOptions(...) directly isn't a workaround, because it replaces the options wholesale and drops the controller's onChange wrapper that re-renders the host.

This adds setOptions to VirtualizerController and WindowVirtualizerController:

It merges a partial update over the options the controller already holds (including the element/window defaults), and skips undefined values so a partial update can't wipe a stored option.
It re-wraps onChange so the host still re-renders, pushes the merged options to the virtualizer, and calls _willUpdate().
Called from willUpdate it doesn't schedule an extra host update, since that render pass hasn't happened yet. Called anywhere else it requests one.

protected willUpdate(changed: PropertyValues<this>) {
  if (changed.has('count')) {
    this.virtualizerController.setOptions({ count: this.count })
  }
}

This picks up the feedback on #1253 (closed without merging): the test now checks the rendered total size (500 then 1000) instead of waiting for an item index the viewport can't show, the changeset is minor because it's new public API, and docs/framework/lit/lit-virtual.md plus the package README now cover setOptions and why to use it instead of getVirtualizer().setOptions(...).

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested this code locally with pnpm run test:pr.

For @tanstack/lit-virtual I ran vitest (13/13 passing), eslint, tsc, the production build, and publint --strict. I didn't run the full test:pr matrix.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

New Features
- Added setOptions support to Lit virtualizer controllers, enabling partial, reactive option updates.
- Updates preserve existing settings when values are omitted or undefined.
- Changes now trigger refreshed rendering while preserving configured change callbacks and controller defaults.
Documentation
- Added guidance for updating virtualizer options reactively through controller lifecycle updates.
- Documented option merging behavior and cautioned against replacing options directly through the underlying virtualizer.

….setOptions VirtualizerController captured options only in its constructor, so later changes such as count never reached the underlying Virtualizer. setOptions merges a partial update over the controller's stored options, keeps the host onChange wrapper, and refreshes the virtualizer. Co-authored-by: Rahul Kashyap <itisrmk@users.noreply.github.com>

changeset-bot · 2026-10-20T08:26:39Z

🦋 Changeset detected

Latest commit: 366e5d6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@tanstack/lit-virtual	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-10-20T08:27:02Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults
Review profile: CHILL
Plan: Advanced
Run ID: 9f2100bb-a42f-4b57-a45a-d8241be9d2a1

📥 Commits

Reviewing files that changed from the base of the PR and between 28ff2ca and 366e5d6.

📒 Files selected for processing: 5

.changeset/lit-controller-set-options.md
docs/framework/lit/lit-virtual.md
packages/lit-virtual/README.md
packages/lit-virtual/src/index.ts
packages/lit-virtual/tests/set-options.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Walkthrough

The Lit virtualizer controllers now expose setOptions for partial option updates. The controller merges defined values, preserves its onChange wrapper, and requests host updates when required. Tests and documentation cover reactive updates.

Changes: Lit virtualizer option updates

Layer / File(s)	Summary
Store and resolve controller options `packages/lit-virtual/src/index.ts`	The base controller stores constructor options and resolves them with an `onChange` wrapper that requests host updates after `updateComplete`.
Apply partial options and validate reactive updates `packages/lit-virtual/src/index.ts`, `packages/lit-virtual/tests/set-options.test.ts`, `docs/framework/lit/lit-virtual.md`, `packages/lit-virtual/README.md`, `.changeset/lit-controller-set-options.md`	`setOptions` merges defined values, ignores unchanged options, and avoids scheduling an extra host update during an active host update. Tests cover callback behavior, host update scheduling, window-controller defaults, and reactive rendering. The documentation and changeset describe the API and its behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Host
  participant VirtualizerController
  participant Virtualizer
  Host->>VirtualizerController: Call setOptions with changed options
  VirtualizerController->>Virtualizer: Apply merged options
  Virtualizer->>VirtualizerController: Invoke wrapped onChange
  VirtualizerController->>Host: Request update when outside an active host update

Suggested reviewers: kadoshms

Merge Risk: ⚪ Minimal · up to 366e5

This adds a setOptions method so reactive Lit properties can update the virtualizer. No concrete merge-blocking risk was found.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (3 skipped: 3 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the primary change: adding setOptions to update Lit virtualizer options after construction.
Description check		The description includes the required Changes, Checklist, and Release Impact sections. It explains the implementation, testing performed, changeset, and the fact that the full test:pr matrix was not r…
Linked Issues check		Issue `#1251` requires updated Lit options to reach the existing virtualizer after construction. `VirtualizerControllerBase.setOptions` merges defined partial values into stored constructor options, pre…
Out of Scope Changes check		The source change is limited to the Lit controller API required by issue `#1251`. The tests verify the new controller behavior. The documentation and minor changeset describe the new public API and its …

Full details: Description check

Explanation

The description includes the required Changes, Checklist, and Release Impact sections. It explains the implementation, testing performed, changeset, and the fact that the full test:pr matrix was not run.

Full details: Linked Issues check

Explanation

Issue #1251 requires updated Lit options to reach the existing virtualizer after construction. VirtualizerControllerBase.setOptions merges defined partial values into stored constructor options, preserves defaults, re-wraps onChange, calls virtualizer.setOptions(...), and calls _willUpdate(). Calls during hostUpdate do not request an extra host update. Tests cover partial updates, undefined, callbacks, update scheduling, window defaults, and a reactive count change from total size 500 to 1000.

Full details: Out of Scope Changes check

Explanation

The source change is limited to the Lit controller API required by issue #1251. The tests verify the new controller behavior. The documentation and minor changeset describe the new public API and its usage. No unrelated platform behavior or unrelated feature is present.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (3 skipped: 3 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

packages/lit-virtual/tests/set-options.test.ts

Parsing error: "parserOptions.project" has been provided for @typescript-eslint/parser.
The file was not found in any of the provided project(s): packages/lit-virtual/tests/set-options.test.ts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

itisrmk · 2026-10-20T08:32:10Z

Hi! Could a maintainer approve the CI workflows for this PR when you have a moment? Thanks.

nx-cloud · 2026-10-20T10:45:07Z

View your CI Pipeline Execution ↗ for commit 366e5d6

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	18s	View ↗
`nx run-many --target=build --exclude=examples/**`	✅ Succeeded	23s	View ↗

☁️ Nx Cloud last updated this comment at 2026-10-20 10:45:11 UTC

pkg-pr-new · 2026-10-20T10:45:48Z

More templates

@tanstack/angular-virtual

npm i https://pkg.pr.new/@tanstack/angular-virtual@1334

@tanstack/lit-virtual

npm i https://pkg.pr.new/@tanstack/lit-virtual@1334

@tanstack/marko-virtual

npm i https://pkg.pr.new/@tanstack/marko-virtual@1334

@tanstack/react-virtual

npm i https://pkg.pr.new/@tanstack/react-virtual@1334

@tanstack/solid-virtual

npm i https://pkg.pr.new/@tanstack/solid-virtual@1334

@tanstack/svelte-virtual

npm i https://pkg.pr.new/@tanstack/svelte-virtual@1334

@tanstack/virtual-core

npm i https://pkg.pr.new/@tanstack/virtual-core@1334

@tanstack/vue-virtual

npm i https://pkg.pr.new/@tanstack/vue-virtual@1334

commit: 366e5d6

piecyk · 2026-10-20T10:47:59Z

Thanks, this looks good. One thing: willUpdate runs before the controllers' hostUpdate() (see performUpdate in @lit/reactive-element), so hostIsUpdating is always false when setOptions is called from willUpdate. It still works, because requestUpdate() does nothing while isUpdatePending is true, but the flag and its comment are misleading. The "during a host update" test also calls hostUpdate() by hand, in an order Lit never uses. Could you remove the flag and the hostUpdate hook and always call requestUpdate()? Lit already merges that into the update that is in progress.

Navigation Menu

Repository navigation

feat(lit-virtual): add setOptions to update virtualizer options after construction - #1334

feat(lit-virtual): add setOptions to update virtualizer options after construction#1334
itisrmk wants to merge 1 commit into
TanStack:mainfrom
itisrmk:cursor/lit-virtual-set-options-1fca

itisrmk commented Oct 20, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented Oct 20, 2026

Uh oh!

coderabbitai Bot commented Oct 20, 2026 •

edited

Loading

Sequence Diagram(s)

Uh oh!

itisrmk commented Oct 20, 2026

Uh oh!

nx-cloud Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Oct 20, 2026

Uh oh!

piecyk commented Oct 20, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

itisrmk commented Oct 20, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Oct 20, 2026

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Sequence Diagram(s)

Uh oh!

itisrmk commented Oct 20, 2026

Uh oh!

nx-cloud Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Oct 20, 2026

Uh oh!

piecyk commented Oct 20, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

itisrmk commented Oct 20, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 20, 2026 •

edited

Loading

nx-cloud Bot commented Oct 20, 2026 •

edited

Loading