Scroll View

A container control aligned with the WinUI 3 ScrollView: when content exceeds the viewport it scrolls, pans, and zooms, with scrollbars styled like WinUI 3's overlay style (a 2px thin thumb that appears once the pointer enters the container; when the pointer moves onto the scrollbar the thumb thickens to 6px, the pill-shaped track expands along with the step buttons at both ends, then collapses when the pointer leaves, and the whole thing fades out after 2s without interaction).

Basic usage (vertical)

By default content-orientation="vertical"; the wheel / touch panning / dragging the scrollbar can all scroll.

Touch panning is owned exclusively by native Touch Events (non-passive listeners that call preventDefault on touchmove), handled separately from pen; therefore native scroll containers inside the content (e.g. code blocks) cannot be scrolled by touch — an existing limitation of the touch model.

<FluereScrollView class="h-80">
  <div v-for="row in rows" :key="row">Row {{ row }} — native Windows 11 scrolling experience</div>
</FluereScrollView>

Horizontal scrolling

With content-orientation="horizontal", the content's height is constrained to the viewport while its width grows freely. Scroll horizontally with Shift + wheel or touch.

<FluereScrollView class="h-40" content-orientation="horizontal">
  <div class="flex gap-fluent-m">…card list…</div>
</FluereScrollView>

Bidirectional scrolling

With content-orientation="both", the content is unconstrained in both horizontal and vertical directions.

<FluereScrollView class="h-72" content-orientation="both">
  <div class="grid grid-cols-6 gap-fluent-m">…cells…</div>
</FluereScrollView>

Nested scrolling

An inner ScrollView sits within the outer content. Mouse-wheel ownership aligns with WinUI 3: when the pointer stays over the inner scroll view, the inner one exclusively owns the wheel, so even if the inner one has already scrolled to its limit the outer one will not scroll along; only when the pointer is moved to outer content outside the inner one does the wheel go to the outer view (touch is owned exclusively by native touch events, pen is exclusively captured by the pointer).

<FluereScrollView class="h-96">
  <!-- Outer content -->
  <FluereScrollView class="h-40">…inner A owns the wheel…</FluereScrollView>
  <FluereScrollView class="h-40">…inner B owns the wheel…</FluereScrollView>
</FluereScrollView>

Focus scrolling

When focus (Tab or programmatic focus()) enters an element inside the content, the element is automatically scrolled into view — aligned with WinUI BringIntoViewOnFocusChange (enabled by default), so keyboard users never leave focus outside the viewport; no animation occurs if the element is already in view. That scroll also fires the bring-into-view event, and the target offset can be cancelled or rewritten in the callback.

When the container gains focus (or focus is inside the content), the arrow keys, PageUp / PageDown, Home / End scroll the view; when an input / textarea / select / contenteditable is hit, the keys are handed back to the input control.

Zoom

With zoom-mode="enabled": Ctrl / Cmd + wheel or pinch-to-zoom, with the pointer position as the zoom center. Aligned with the WinUI min-zoom-factor / max-zoom-factor constraints.

<FluereScrollView class="h-80" content-orientation="both" zoom-mode="enabled">
  <!-- Ctrl / Cmd + wheel, or pinch to zoom -->
</FluereScrollView>

Scrollbar visibility

vertical-scroll-bar-visibility supports auto (default, overlay) / visible (always shown) / hidden (still scrollable).

<FluereScrollView>…auto (default, overlay)…</FluereScrollView>
<FluereScrollView vertical-scroll-bar-visibility="visible">…always shown…</FluereScrollView>
<FluereScrollView vertical-scroll-bar-visibility="hidden">…hidden but scrollable…</FluereScrollView>

Programmatic API

Aligned with the WinUI methods: scrollTo / scrollBy / zoomTo / zoomBy / addScrollVelocity / addZoomVelocity / bringIntoView (supporting animation and correlation IDs), plus the read-only properties horizontalOffset / verticalOffset / zoomFactor / extentWidth / extentHeight / viewportWidth / viewportHeight / scrollableWidth / scrollableHeight / state / currentAnchor. Full signatures are in the 「Methods」 and 「Readonly properties」 tables below.

<template>
  <FluereScrollView
    ref="sv"
    content-orientation="both"
    zoom-mode="enabled"
    @view-changed="refreshReadout"
  >
    …content…
  </FluereScrollView>
  <button @click="sv?.scrollBy(0, 120)">Scroll down 120px</button>
  <button @click="sv?.scrollTo(0, 0)">Back to top</button>
  <button @click="sv?.zoomBy(0.25)">Zoom in</button>
</template>

<script setup lang="ts">
const sv = ref<InstanceType<typeof FluereScrollView>>()
</script>

Events

view-changed / extent-changed / state-changed / scroll-animation-starting / scroll-completed / zoom-animation-starting / zoom-completed / anchor-requested / bring-into-view, with payloads in the 「Events」 table below. These are component events (@event); the DOM command events meant for page automation are in 「Agent / Automation access」, their names carry the fluere: prefix and they are dispatched on the root element.

<FluereScrollView
  @view-changed="logEvent('view-changed')"
  @state-changed="logEvent(`state → ${$event}`)"
  @scroll-completed="logEvent(`scroll-completed #${$event.correlationId}`)"
>
  …content…
</FluereScrollView>

Agent / Automation access

This component expresses its offset through a content transform and its presenter is overflow: clip (not a native scroll container), so the native scrolling semantics of browsers and automation tools do not apply here: scrollTop is always 0, and scrollBy / scrollIntoView / scrollIntoViewIfNeeded can find no scrollable ancestor (native auto-scrolling before Playwright clicks an element outside the viewport also fails, which is the pitfall documented in style-spec §7). For this the component provides two DOM-based paths, neither of which requires touching the component instance:

• Read-only reflection: the root element always carries a set of state attributes for determining 「whether it moved / how much is left」;
• Command events: dispatching fluere:* events on the root element drives the scrolling, and receipts are received once applied.

Read-only reflection attributes

Once rounded, equality comparisons can safely determine 「whether it reached the end」 (data-scroll-y === data-scroll-max-y). These attributes are rewritten frame by frame when the offset changes, do not match them in CSS (otherwise style recalculation is triggered on every frame during animation; a contract test in the repo guards this rule).

Command events

Dispatch on the component root element (.fui-scrollview), with bubbles: true, so they can also be attached at the page level.

An invalid payload (a non-finite number, an unresolvable target) is a no-op and does not throw; bring-into-view only accepts elements inside the content. Passing animationMode as 'disabled' skips the animation, which suits deterministic positioning before a screenshot; setting agentCommands to false disables the command events (read-only reflection is kept).

const el = document.querySelector('.fui-scrollview')

// 1. Read state first: how much more needs to scroll?
const remaining = Number(el.dataset.scrollMaxY) - Number(el.dataset.scrollY)

// 2. Dispatch the command (bubbles lets page-level listeners receive it too)
el.dispatchEvent(
  new CustomEvent('fluere:scroll-by', { detail: { y: remaining, animationMode: 'disabled' } }),
)

// 3. Wait for the receipt before screenshotting / asserting
await new Promise((resolve) =>
  el.addEventListener('fluere:scroll-settled', resolve, { once: true }),
)

<FluereScrollView ref="sv" label="Log list" @view-changed="refresh">
  …content…
</FluereScrollView>

// Read-only reflection: read the DOM, never touch the instance
const root = sv.value.$el
const { scrollY, scrollMaxY } = root.dataset

// Command + receipt
root.addEventListener('fluere:scroll-settled', refresh)
root.dispatchEvent(
  new CustomEvent('fluere:bring-into-view', {
    detail: { selector: '[data-row="24"]' },
    bubbles: true,
  }),
)

Native semantics that still do not apply: the component is not a native scroll container, so el.scrollTop, el.scrollBy(), el.scrollIntoView(), CDP DOM.scrollIntoViewIfNeeded, the browser's 「find in page」 and #:~:text= text fragment anchoring still do not work — use the command events above instead. There is another existing path: when focus enters an element in the content, the component automatically scrolls it into view per BringIntoViewOnFocusChange (aligned with WinUI, see bringIntoView in the 「Methods」 table).

API

Props

Events

Methods

Called through a template ref; each returns the correlationId of this operation, for matching against the payloads of scroll-completed / zoom-completed.

ScrollingScrollOptions / ScrollingZoomOptions take 'disabled' \| 'enabled' \| 'auto' for animationMode (default 'auto'), plus a placeholding snapPointsMode.

Readonly properties

Slots

Wheel ownership (aligned with WinUI 3): when the pointer is inside this component and that direction is actually scrollable, this wheel is owned exclusively by the component — even at the scroll limit it will not scroll the outer ScrollView; when horizontal/verticalScrollChainMode is auto / never, reaching the limit swallows the wheel (equivalent to overscroll-behavior: contain), and only when it is always is the unconsumed remaining delta explicitly handed to the outer view. When the current direction has no scrollable content, or that direction is disabled, the wheel is not owned and bubbles to the outer view. Touch is owned exclusively by native touch events and pen is exclusively captured by the pointer; neither goes through this determination.