Search documentation

Search all pages, headings and text, in the current package or topic or in all documentation.

Anchoring and scrolling

What keeps its place when the geometry changes, and how scroll requests converge.

@workspace/active-virtual 2.1.0Status unknowncontent differs from the recorded release 2.1.0baseline ce081dc3

Older items above the viewport, without a jumpClient

50 messages, from Message 100

Anchoring#

When geometry changes (a measurement, an insertion, a new estimate, a reset), one item keeps its distance to the viewport, and the axis compensates the scroll offset.

anchorKeeps in place
{kind: 'start-edge'} (the default)the first item starting at or after the viewport start
{kind: 'end-edge'}the last item ending at or before the viewport end
{kind: 'keyed', identity, fallback?}one item you name
{kind: 'focus', fallback?}the item that holds focus
{kind: 'none'}nothing

startEdge and endEdge decide what happens when the viewport sits at an edge: follow stays at that edge (a chat that follows new messages at the end), preserve keeps the item anchor. In the example above startEdge: 'preserve' keeps the first visible message in place even at the very top.

When the anchored item is removed, the nearest surviving successor takes its place, else the nearest predecessor, else the edge.

Scroll requests#

  • align: start, center, end, or auto (no movement when the item is already fully visible).
  • behavior: instant (default) or smooth.
  • The latest request wins. A request to an item converges as its surroundings are measured; it gives up after a bounded number of writes and reports intent-gave-up.
  • A user scroll (wheel, touch, the scrollbar) ends a request.
  • A target the browser cannot reach is reported (scroll-unreachable) and never claimed as reached.

Diagnostics#

Pass onDiagnostic (or a sink to createAxisStore) to receive warnings such as intent-target-missing. Without one, diagnostics are dropped; the package never writes to the console.

This page as Markdown