The pin property takes an option called index to specify (by number) which child element you want to frame in the viewport. If you want, you can also use the block option to indicate how the element should be framed relative to the viewport; block behaves identically to the same option in the scrollIntoView() method.

When you pin a layout, it remains pinned until the user intentionally scrolls the view, at which point it is automatically "unpinned". When this occurs, the virtualizer fires an unpinned event. Unless you're sure you'll only render your virtualizer once, you should listen for the unpinned event so you can omit the pin property when you re-render the virtualizer and avoid snapping the view back to the previously pinned position. [TODO: link to an example]

#### A note on smooth scrolling

As noted above, @lit-labs/virtualizer essentially "just works" with the browser's native scrolling APIs, including smooth scrolling (as specified via the behavior: 'smooth' option).

That said, depending on what layout you're using and what browser you're scrolling in, you may sometimes notice a slight "hitch" in the scrolling animation, where it momentarily slows—usually shortly before reaching its destination.

This only occurs with the flow layout and is noticeable mainly (perhaps only) in Chromium-based browsers. It happens when the layout has been estimating the sizes of child elements it hasn't yet measured and needs to correct errors in its estimates while a smooth scrolling animation is in progress.

This is a known limitation which, unless smooth scrolling in Chromium evolves to behave more like other browsers, probably can't be addressed without changing @lit-labs/virtualizer to use JavaScript-based scrolling in place of native scrolling.

$3

An alternative way to use @lit-labs/virtualizer is via the virtualize directive; this directive turns its parent element into a virtualizer.

The virtualize directive is useful primarily if your project utilizes Lit templates but not the LitElement base class and you want to keep your imports to a minimum.

It can also be useful in cases like the one below, where we want to virtualize an unordered list (

) element and don't want or need a separate container for its
• children:

  `js
render() {
return html
  

  
  ${virtualize({
  items: this.contacts,
  renderItem: contact => html
  • ${contact.name}
  
  })}
  
  
  ;
}
`

  The capabilities of the virtualizer directive are the same as those of the element. The configuration APIs are the same as well, except that features expressed as properties and attributes on the element are instead expressed as properties in an options object passed as the single argument to the virtualize directive.

  $3

  In addition to its declarative configuration options, a virtualizer exposes a handful of imperative APIs. The element exposes these APIs directly, but to use them with the virtualize directive you need to get a reference to the virtualizer. You do this by first getting a reference to the virtualizer's host element (the element within which you rendered the directive) and then using the virtualizerRef symbol to get a reference to the virtualizer itself. For example:

  `ts
import {html, LitElement} from 'lit';
import {customElement, property, query} from 'lit/decorators.js';
// Import the virtualizerRef symbol along with the directive
import {virtualize, virtualizerRef} from '@lit-labs/virtualizer/virtualize.js';

  @customElement('my-items')
export class MyItems extends LitElement {
data = new Array(100).fill('').map((i, n) => ({text: Item ${n}}));

  @query('ul')
list: HTMLUListElement;

  render() {
return html
  

  
  ${virtualize({
  items: this.data,
  renderItem: (i) => html
  • ${i.text}
  ,
  })}
  
  
  ;
  }

  scrollToListItem(idx) {
// Use the virtualizerRef symbol as a property key on the
// host element to access the virtualizer reference
this.list[virtualizerRef].element(idx).scrollIntoView();
}
}
`

  ResizeObserver dependency

  Virtualizer depends on the standard [ResizeObserver]() API, which is supported in all modern browsers. In case your browser support matrix includes older browsers that don't implement ResizeObserver, the Virtualizer package includes a ResizeObserver polyfill that is known to be compatible with Virtualizer. This is a forked version of Denis Rul's resize-observer-polyfill package, which we modified to extend its observations into shadow roots.

  $3

  The package also includes a simple mechanism for loading the ResizeObserver polyfill. This mechanism uses feature detection to determine whether the polyfill is required; if it is, then the polyfill is automatically loaded and provided directly to Virtualizer.

  You need to invoke the loader—which is asynchronous—and await its return before running any code that would cause a virtualizer to be instantiated. The simplest way to do this is to load virtualizer itself with a dynamic import() statement. For example:

  `js
import {loadPolyfillIfNeeded} from '@lit-labs/virtualizer/polyfillLoaders/ResizeObserver.js';

  async function load() {
await loadPolyfillIfNeeded();
await import('@lit-labs/virtualizer');
}
`

  $3

  In case you want to make the ResizeObserver polyfill available for use outside of Virtualizer or have other specialized polyfill-loading requirements, you can alternatively import the polyfill directly and write your own custom code for loading and exposing it.

  If you choose this option, there are two ways you can make the polyfill available for Virtualizer to use:

  - Expose the polyfill via window.ResizeObserver so that Virtualizer can access it just as it would the native implementation.
- Pass the polyfill constructor to Virtualizer's provideResizeObserver() function.

  Either way, you should do so before instantiating any virtualizers, just as when you use the provided loader.

  Here's how you would import the polyfill and the provideResizeObserver() function statically:

  `js
import ResizeObserverPolyfill from '@lit-labs/virtualizer/polyfills/resize-observer-polyfill/ResizeObserver.js';
import {provideResizeObserver} from '@lit-labs/virtualizer/polyfillLoaders/ResizeObserver.js';
`

  More typically, though, you'd import them dynamically:

  `js
async function myCustomLoader() {
// Write whatever custom logic you need, using feature detection, etc...

  // If you need to load the polyfill, do it like this:
const ResizeObserverPolyfill = await import(
'@lit-labs/virtualizer/polyfills/resize-observer-polyfill/ResizeObserver.js'
).default;

  // To install the polyfill globally, do something like this:
window.ResizeObserver = ResizeObserverPolyfill;

  // Or to provide it to Virtualizer, do something like this:
const {provideResizeObserver} = await import(
'@lit-labs/virtualizer/polyfillLoaders/ResizeObserver.js'
);
provideResizeObserver(ResizeObserverPolyfill);
}
`

  $3

  When using Virtualizer, you may see this error in your console and depending on your testing framework, it may be causing your tests to fail. The error itself is benign and only means that the ResizeObserver was not able to deliver all observations within a single animation frame. It may be safely ignored, but it may be necessary to instruct your framework to ignore it as well to prevent unnecessary side-effects and error-handling.

  To assist with this, a few functions are provided in the support folder. These functions are independent of each other and you will need to choose which best fits to your situation.

  #### window.onerror patches

  Testing frameworks like Mocha define an onerror handler directly on window which catch any unhandled exceptions and report them as failures. The following two solutions wrap this handler to ignore the loop limit errors specifically.

  #### setupIgnoreWindowResizeObserverLoopErrors()

  The simplest approach is to use this function to wrap and unwrap the onerror handler before and after each test. With a Mocha setup you would use it like this:

  `ts
import {setupIgnoreWindowResizeObserverLoopErrors} from '@lit-labs/virtualizer/support/resize-observer-errors.js';

  describe('My virtualized collection', () => {
setupIgnoreWindowResizeObserverLoopErrors(beforeEach, afterEach);

  it('does this and that', () => {
/ test stuff /
});
});
`

  By handing setupIgnoreWindowResizeObserverLoopErrors the beforeEach and afterEach callbacks, it is able to define the appropriate setup and teardown for you. The only case where this may not work is if you are for some reason patching window.onerror as well; if the teardown step does not see the expected handler in place before restoring the original handler it will throw and error to alert you to an "out-of-sequence interceptor teardown." In the rare case you have competing patches of window.onerror you can use the next option, ignoreWindowResizeObserverLoopErrors.

  #### ignoreWindowResizeObserverLoopErrors()

  This method allows you to be specific about the timing/ordering that the window.onerror patch is removed, which may be necessary if you have more complicated setups and/or multiple patches to window.onerror. ignoreWindowResizeObserverLoopErrors returns a function that restores onerror to its original form prior to the patch. Notice that multiple patches generally need to removed in reverse order.

  `ts
import {ignoreWindowResizeObserverLoopErrors} from '@lit-labs/virtualizer/support/resize-observer-errors.js';

  describe('My virtualized collection', () => {
let teardown;

  beforeEach(() => (teardown = ignoreWindowResizeObserverLoopErrors()));
beforeEach(() => applyOtherWindowOnErrorPatch());

  afterEach(() => removeOtherWindowOnErrorPatch());
afterEach(() => teardown());

  it('does this and that', () => {
// etc
});
});
`

  #### preventResizeObserverLoopErrorEventDefaults()

  If an explicit window.onerror handler function has not been defined, you may be able to swallow up the loop limit errors with an event listener. This function adds that event listener to window and attempts to ignore and prevent any further event propogation or behaviors as a result.

  `ts
import {preventResizeObserverLoopErrorEventDefaults} from '@lit-labs/virtualizer/support/resize-observer-errors.js';

  preventResizeObserverLoopErrorEventDefaults();
`

  If you need to remove the event listener that this function adds at some point, you can assign the return of the function, which is a function that removes the listener, to a variable for later use:

  `ts
const teardown = preventResizeObserverLoopErrorEventDefaults();

  / some time later... /
teardown();
`

  Note that for this to be effective, you'll need to call it to add the event listener to window as early as you can, to ensure it is in place prior to any other event listeners who would otherwise receive the event first.

  API Reference

  $3

  Type: Array

  An array of items (JavaScript values, typically objects) representing the child elements of the virtualizer.

  The types of values you use to represent your items are entirely up to you, as long as your renderItem function can transform each value into a child element.

  $3

  Type: (item: T, index?: number) => TemplateResult

  A function that returns a Lit TemplateResult. It will be used to generate a child element for each item in the items array.

  $3

  Type: Boolean

  Optional. If this attribute is present (or, in the case of the virtualize directive, if this property has a truthy value), then the virtualizer itself will be a scroller. Otherwise, the virtualizer will not scroll but will size itself to take up enough space for all of its children, including those that aren't currently present in the DOM.

  $3

  Type: (index: number, position?: string) => void

  where position is: 'start'|'center'|'end'|'nearest'

  Scroll to the item at the given index. Place the item at the given position within the viewport. For example, if index is 100 and position is end, then the bottom of the item at index 100 will be at the bottom of the viewport. Position defaults to start.

  _Note: Details of the scrollToIndex API are likely to change before the 1.0 release, but changes required to your existing code should be minimal and mechanical in nature._

  Example usage:

  `js
// Where myVirtualizer is a reference to a instance, this
// will scroll to the 100th item and put it in the center of the viewport.
myVirtualizer.scrollToIndex(100, 'center');
`

  $3

  Fired whenever a change to the viewport (due to scrolling or resizing) affects the set of virtualizer child elements that are currently visible. The first property represents the index of the first visible element; the last property represents the index of the last visible element.

  $3

  Fired whenever a virtualizer adds child elements to the DOM, or removes child elements from the DOM. The first property represents the index of the first element currently present in the DOM; the last` property represents the index of the last element currently present in the DOM.

  Note that a virtualizer maintains a "buffer" of elements that are in the DOM but just outside the viewport, so the set of elements in the DOM will be somewhat larger than the set of visible elements.