Message Scroller

<script setup lang="ts">
const messages = [
  { id: 'm1', role: 'user', text: 'What does a message scroller actually have to do?' },
  { id: 'm2', role: 'assistant', text: 'Keep the reader where they expect to be. That means following a reply while it streams, but never fighting someone who scrolls up to re-read something.' },
  { id: 'm3', role: 'user', text: 'And when older history loads above?' },
  { id: 'm4', role: 'assistant', text: 'The reading position is preserved — the message you were looking at stays exactly where it was, instead of being pushed down the page.' },
  { id: 'm5', role: 'user', text: 'What about jumping around the thread?' },
  { id: 'm6', role: 'assistant', text: 'Every item can carry a messageId, so you can scroll to any of them on demand, with the alignment you want.' },
]
</script>

<template>
  <div class="h-80 w-full border rounded-lg bg-background">
    <NMessageScrollerProvider>
      <NMessageScroller>
        <NMessageScrollerViewport>
          <NMessageScrollerContent class="p-4">
            <NMessageScrollerItem
              v-for="message in messages"
              :key="message.id"
              :message-id="message.id"
            >
              <div
                class="max-w-[80%] rounded-lg px-3 py-2 text-sm"
                :class="message.role === 'user'
                  ? 'ml-auto bg-primary text-primary-foreground'
                  : 'bg-muted text-foreground'"
              >
                {{ message.text }}
              </div>
            </NMessageScrollerItem>
          </NMessageScrollerContent>
        </NMessageScrollerViewport>

        <NMessageScrollerButton />
      </NMessageScroller>
    </NMessageScrollerProvider>
  </div>
</template>

<script setup lang="ts">
interface Message {
  id: string
  role: 'user' | 'assistant'
  text: string
}

const REPLY = 'While a reply streams, the viewport stays pinned to the live edge. Scroll up and it lets go — new chunks arrive without moving you. Come back to the bottom and it picks the thread up again.'

const messages = ref<Message[]>([
  { id: 'm1', role: 'user', text: 'Stream me something long enough to scroll.' },
  { id: 'm2', role: 'assistant', text: REPLY },
])

const streaming = ref(false)
let timer: ReturnType<typeof setInterval> | null = null
let uid = 2

function stop() {
  if (timer) {
    clearInterval(timer)
    timer = null
  }
  streaming.value = false
}

function stream() {
  if (streaming.value)
    return
  uid += 1
  messages.value.push({ id: `m${uid}`, role: 'user', text: 'Once more, please.' })
  uid += 1
  messages.value.push({ id: `m${uid}`, role: 'assistant', text: '' })
  // mutate through the array proxy so every chunk triggers reactivity
  const reply = messages.value[messages.value.length - 1]!
  streaming.value = true

  const words = `${REPLY} ${REPLY}`.split(' ')
  let index = 0
  timer = setInterval(() => {
    if (index >= words.length) {
      stop()
      return
    }
    reply.text += `${words[index]} `
    index += 1
  }, 70)
}

onBeforeUnmount(stop)
</script>

<template>
  <div class="w-full flex flex-col gap-3">
    <NButton
      btn="outline-gray"
      size="sm"
      label="Stream a reply"
      class="self-start"
      :disabled="streaming"
      @click="stream"
    />

    <div class="h-80 border rounded-lg bg-background">
      <NMessageScrollerProvider auto-scroll>
        <NMessageScroller>
          <NMessageScrollerViewport>
            <NMessageScrollerContent class="p-4">
              <NMessageScrollerItem
                v-for="message in messages"
                :key="message.id"
                :message-id="message.id"
              >
                <div
                  class="max-w-[80%] rounded-lg px-3 py-2 text-sm"
                  :class="message.role === 'user'
                    ? 'ml-auto bg-primary text-primary-foreground'
                    : 'bg-muted text-foreground'"
                >
                  {{ message.text }}
                </div>
              </NMessageScrollerItem>
            </NMessageScrollerContent>
          </NMessageScrollerViewport>

          <NMessageScrollerButton />
        </NMessageScroller>
      </NMessageScrollerProvider>
    </div>
  </div>
</template>

<script setup lang="ts">
interface Message {
  id: string
  role: 'user' | 'assistant'
  text: string
}

const messages = ref<Message[]>([
  { id: 'm1', role: 'user', text: 'First question of the thread.' },
  { id: 'm2', role: 'assistant', text: 'And the answer to it, which is long enough to take up a bit of room in the transcript so there is something to scroll past.' },
  { id: 'm3', role: 'user', text: 'A follow-up question.' },
  { id: 'm4', role: 'assistant', text: 'Another answer. Each user turn is marked as a scroll anchor, so a new turn is moved to the top of the viewport with a peek of the previous exchange left above it.' },
])

let uid = 4

function askAgain() {
  uid += 1
  messages.value.push({ id: `m${uid}`, role: 'user', text: `Question ${Math.ceil(uid / 2)} — watch this one move to the top.` })
  uid += 1
  messages.value.push({ id: `m${uid}`, role: 'assistant', text: 'The reply lands underneath the anchored question, so the turn reads from its beginning instead of appearing halfway up the viewport.' })
}
</script>

<template>
  <div class="w-full flex flex-col gap-3">
    <NButton btn="outline-gray" size="sm" label="Ask a new question" class="self-start" @click="askAgain" />

    <div class="h-80 border rounded-lg bg-background">
      <NMessageScrollerProvider auto-scroll default-scroll-position="last-anchor">
        <NMessageScroller>
          <NMessageScrollerViewport>
            <NMessageScrollerContent class="p-4">
              <NMessageScrollerItem
                v-for="message in messages"
                :key="message.id"
                :message-id="message.id"
                :scroll-anchor="message.role === 'user'"
              >
                <div
                  class="max-w-[80%] rounded-lg px-3 py-2 text-sm"
                  :class="message.role === 'user'
                    ? 'ml-auto bg-primary text-primary-foreground'
                    : 'bg-muted text-foreground'"
                >
                  {{ message.text }}
                </div>
              </NMessageScrollerItem>
            </NMessageScrollerContent>
          </NMessageScrollerViewport>

          <NMessageScrollerButton />
        </NMessageScroller>
      </NMessageScrollerProvider>
    </div>
  </div>
</template>

<script setup lang="ts">
interface Message {
  id: string
  role: 'user' | 'assistant'
  text: string
}

let oldest = 0

function olderPage(): Message[] {
  return Array.from({ length: 4 }, (_, i) => {
    oldest -= 1
    return {
      id: `old${oldest}`,
      role: (i % 2 === 0 ? 'user' : 'assistant') as Message['role'],
      text: `Older message ${oldest}. Loading history above the reader must not move the message they are reading.`,
    }
  }).reverse()
}

const messages = ref<Message[]>([
  { id: 'm1', role: 'user', text: 'Scroll to the top and load the history above.' },
  { id: 'm2', role: 'assistant', text: 'The scroller records where the first visible message sits, then puts it back after the prepend — so the transcript grows upward without the page jumping under you.' },
  { id: 'm3', role: 'user', text: 'Try it a few times in a row.' },
  { id: 'm4', role: 'assistant', text: 'Each page of history is added above, and your reading position stays put to the pixel.' },
])

function loadOlder() {
  messages.value.unshift(...olderPage())
}
</script>

<template>
  <div class="w-full flex flex-col gap-3">
    <NButton btn="outline-gray" size="sm" label="Load older messages" class="self-start" @click="loadOlder" />

    <div class="h-80 border rounded-lg bg-background">
      <NMessageScrollerProvider>
        <NMessageScroller>
          <NMessageScrollerViewport>
            <NMessageScrollerContent class="p-4">
              <NMessageScrollerItem
                v-for="message in messages"
                :key="message.id"
                :message-id="message.id"
              >
                <div
                  class="max-w-[80%] rounded-lg px-3 py-2 text-sm"
                  :class="message.role === 'user'
                    ? 'ml-auto bg-primary text-primary-foreground'
                    : 'bg-muted text-foreground'"
                >
                  {{ message.text }}
                </div>
              </NMessageScrollerItem>
            </NMessageScrollerContent>
          </NMessageScrollerViewport>

          <NMessageScrollerButton direction="start" />
          <NMessageScrollerButton />
        </NMessageScroller>
      </NMessageScrollerProvider>
    </div>
  </div>
</template>

<script setup lang="ts">
const messages = Array.from({ length: 5 }, (_, turn) => [
  {
    id: `q${turn + 1}`,
    role: 'user' as const,
    text: `Question ${turn + 1} — the anchor for this turn.`,
  },
  {
    id: `a${turn + 1}`,
    role: 'assistant' as const,
    text: `Answer ${turn + 1}. Long enough that the turns do not all fit at once, so jumping between them actually moves the viewport and the visibility state changes as you go.`,
  },
]).flat()

const targets = Array.from({ length: 5 }, (_, turn) => ({
  id: `q${turn + 1}`,
  label: `Turn ${turn + 1}`,
}))
</script>

<template>
  <NMessageScrollerProvider default-scroll-position="start">
    <div class="w-full flex flex-col gap-3">
      <div class="h-80 border rounded-lg bg-background">
        <NMessageScroller>
          <NMessageScrollerViewport>
            <NMessageScrollerContent class="p-4">
              <NMessageScrollerItem
                v-for="message in messages"
                :key="message.id"
                :message-id="message.id"
                :scroll-anchor="message.role === 'user'"
              >
                <div
                  class="max-w-[80%] rounded-lg px-3 py-2 text-sm"
                  :class="message.role === 'user'
                    ? 'ml-auto bg-primary text-primary-foreground'
                    : 'bg-muted text-foreground'"
                >
                  {{ message.text }}
                </div>
              </NMessageScrollerItem>
            </NMessageScrollerContent>
          </NMessageScrollerViewport>

          <NMessageScrollerButton direction="start" />
          <NMessageScrollerButton />
        </NMessageScroller>
      </div>

      <ExampleVueMessageScrollerJumpControls :targets="targets" />
    </div>
  </NMessageScrollerProvider>
</template>

<script setup lang="ts">
// This composer is rendered by the same component that renders the provider, so
// it sits outside the context and cannot call useMessageScroller(). It drives
// the transcript through a template ref on NMessageScroller instead.
const scroller = useTemplateRef('scroller')

const messages = ref([
  { id: 'm1', role: 'user', text: 'Can a composer outside the provider still scroll the transcript?' },
  { id: 'm2', role: 'assistant', text: 'Yes — through a template ref. The provider puts the context below itself, so anything rendered as a sibling of the transcript has nothing to inject, and this composer is rendered by the same component that renders the provider.' },
  { id: 'm3', role: 'user', text: 'What does the ref give me?' },
  { id: 'm4', role: 'assistant', text: 'The same three commands useMessageScroller() returns — scrollToEnd, scrollToStart and scrollToMessage. NMessageScroller exposes them on its instance, so the context is not the only way in.' },
  { id: 'm5', role: 'user', text: 'And the send button?' },
  { id: 'm6', role: 'assistant', text: 'Append the message, await nextTick() so the new item is in the DOM, then call scrollToEnd. Without the tick you would scroll to where the end used to be.' },
  { id: 'm7', role: 'user', text: 'Does Top work the same way?' },
  { id: 'm8', role: 'assistant', text: 'It calls scrollToStart off the same ref. Send a few messages, then jump back up here to see both ends of the transcript move.' },
])

const draft = ref('')

async function send() {
  const text = draft.value.trim()
  if (!text)
    return

  messages.value.push({ id: `m${messages.value.length + 1}`, role: 'user', text })
  draft.value = ''

  // The append has to be in the DOM before the new end can be scrolled to.
  await nextTick()
  scroller.value?.scrollToEnd({ behavior: 'smooth' })
}
</script>

<template>
  <div class="w-full flex flex-col gap-3">
    <div class="h-80 border rounded-lg bg-background">
      <NMessageScrollerProvider>
        <NMessageScroller ref="scroller">
          <NMessageScrollerViewport>
            <NMessageScrollerContent class="p-4">
              <NMessageScrollerItem
                v-for="message in messages"
                :key="message.id"
                :message-id="message.id"
              >
                <div
                  class="max-w-[80%] rounded-lg px-3 py-2 text-sm"
                  :class="message.role === 'user'
                    ? 'ml-auto bg-primary text-primary-foreground'
                    : 'bg-muted text-foreground'"
                >
                  {{ message.text }}
                </div>
              </NMessageScrollerItem>
            </NMessageScrollerContent>
          </NMessageScrollerViewport>

          <NMessageScrollerButton />
        </NMessageScroller>
      </NMessageScrollerProvider>
    </div>

    <div class="flex items-center gap-2">
      <NInput
        v-model="draft"
        placeholder="Write a message, then send"
        :una="{ inputWrapper: 'flex-1' }"
        @keydown.enter="send"
      />
      <NButton
        btn="outline-gray"
        size="sm"
        label="Send"
        @click="send"
      />
      <NButton
        btn="outline-gray"
        size="sm"
        label="Top"
        @click="scroller?.scrollToStart({ behavior: 'smooth' })"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import type { NMessageScrollerProviderProps } from '../../types'
import { provideMessageScroller } from './useMessageScroller'

const props = defineProps<NMessageScrollerProviderProps>()

provideMessageScroller(props)
</script>

<template>
  <slot />
</template>

<script setup lang="ts">
import type { NMessageScrollerProps } from '../../types'
import { cn } from '../../utils'
import { useMessageScrollerContext } from './useMessageScroller'

const props = defineProps<NMessageScrollerProps>()

const { autoscrolling, scrollableAttr, scrollToEnd, scrollToMessage, scrollToStart } = useMessageScrollerContext()

/**
 * Exposed for controls the provider cannot reach by injection — a composer or
 * toolbar rendered as a sibling of this subtree, or in the setup scope that
 * renders `NMessageScrollerProvider`, cannot inject a context provided below it.
 *
 * Deliberate divergence from the shadcn-vue source, which exposes nothing here
 * — keep it when diffing against upstream. See #645.
 */
defineExpose({ scrollToEnd, scrollToMessage, scrollToStart })
</script>

<template>
  <div
    data-slot="message-scroller"
    :data-scrollable="scrollableAttr"
    :data-autoscrolling="autoscrolling ? '' : undefined"
    :class="cn(
      'group/message-scroller message-scroller',
      props.una?.messageScroller,
      props.class,
    )"
  >
    <slot />
  </div>
</template>

<script setup lang="ts">
import type { NMessageScrollerViewportProps } from '../../types'
import { onBeforeUnmount, onMounted, useTemplateRef, watch } from 'vue'
import { cn } from '../../utils'
import { isScrollTowardStartKey, SCROLL_KEYS, useMessageScrollerContext } from './useMessageScroller'

const props = withDefaults(defineProps<NMessageScrollerViewportProps>(), {
  preserveScrollOnPrepend: true,
})

const {
  autoscrolling,
  handleResize,
  scrollableAttr,
  setPreserveScrollOnPrepend,
  setViewportElement,
  syncAfterScroll,
  userScrollIntent,
} = useMessageScrollerContext()

const viewportEl = useTemplateRef<HTMLElement>('viewport')

watch(() => props.preserveScrollOnPrepend, setPreserveScrollOnPrepend, { immediate: true })

// Only a gesture that carries the reader toward the start releases autoScroll:
// wheeling or paging down while already at the live edge moves nothing.
function onWheel(event: WheelEvent) {
  userScrollIntent(event.deltaY < 0)
}

let touchStartY: number | null = null

function onTouchStart(event: TouchEvent) {
  touchStartY = event.touches[0]?.clientY ?? null
}

function onTouchMove(event: TouchEvent) {
  const y = event.touches[0]?.clientY ?? null
  // dragging the finger down pulls the transcript toward the start
  userScrollIntent(touchStartY === null || y === null ? true : y > touchStartY)
}

function onKeyDown(event: KeyboardEvent) {
  if (SCROLL_KEYS.has(event.key))
    userScrollIntent(isScrollTowardStartKey(event))
}

let resizeObserver: ResizeObserver | null = null
let resizeFrame = 0

onMounted(() => {
  const viewport = viewportEl.value
  setViewportElement(viewport)
  if (!viewport || typeof ResizeObserver === 'undefined')
    return
  resizeObserver = new ResizeObserver(() => {
    window.cancelAnimationFrame(resizeFrame)
    resizeFrame = window.requestAnimationFrame(handleResize)
  })
  resizeObserver.observe(viewport)
})

onBeforeUnmount(() => {
  window.cancelAnimationFrame(resizeFrame)
  resizeObserver?.disconnect()
  resizeObserver = null
  setViewportElement(null)
})
</script>

<template>
  <div
    ref="viewport"
    data-slot="message-scroller-viewport"
    role="region"
    aria-label="Messages"
    :tabindex="0"
    :data-scrollable="scrollableAttr"
    :data-autoscrolling="autoscrolling ? '' : undefined"
    :class="cn(
      'message-scroller-viewport',
      props.una?.messageScrollerViewport,
      props.class,
    )"
    @scroll="syncAfterScroll()"
    @wheel="onWheel"
    @touchstart="onTouchStart"
    @touchmove="onTouchMove"
    @keydown="onKeyDown"
  >
    <slot />
  </div>
</template>

<script setup lang="ts">
import type { NMessageScrollerContentProps } from '../../types'
import { onBeforeUnmount, onMounted, useTemplateRef } from 'vue'
import { cn } from '../../utils'
import { useMessageScrollerContext } from './useMessageScroller'

const props = defineProps<NMessageScrollerContentProps>()

const {
  handleContentChange,
  handleResize,
  setContentElement,
  setSpacerElement,
} = useMessageScrollerContext()

const contentRef = useTemplateRef<HTMLElement>('content')
const spacerRef = useTemplateRef<HTMLElement>('spacer')

let mutationObserver: MutationObserver | null = null
let resizeObserver: ResizeObserver | null = null
let resizeFrame = 0

onMounted(() => {
  const content = contentRef.value
  if (!content)
    return

  setContentElement(content)
  setSpacerElement(spacerRef.value ?? null)
  handleContentChange()

  if (typeof MutationObserver !== 'undefined') {
    mutationObserver = new MutationObserver(() => handleContentChange())
    mutationObserver.observe(content, { childList: true })
  }

  if (typeof ResizeObserver !== 'undefined') {
    resizeObserver = new ResizeObserver(() => {
      window.cancelAnimationFrame(resizeFrame)
      resizeFrame = window.requestAnimationFrame(handleResize)
    })
    resizeObserver.observe(content)
  }
})

onBeforeUnmount(() => {
  window.cancelAnimationFrame(resizeFrame)
  mutationObserver?.disconnect()
  resizeObserver?.disconnect()
  mutationObserver = null
  resizeObserver = null
  setContentElement(null)
  setSpacerElement(null)
})
</script>

<template>
  <div
    ref="content"
    data-slot="message-scroller-content"
    role="log"
    aria-relevant="additions"
    :class="cn(
      'message-scroller-content',
      props.una?.messageScrollerContent,
      props.class,
    )"
  >
    <slot />
    <div
      ref="spacer"
      aria-hidden="true"
      data-message-scroller-spacer=""
      hidden
      :class="props.spacerClass"
    />
  </div>
</template>

<script setup lang="ts">
import type { NMessageScrollerItemProps } from '../../types'
import { onBeforeUnmount, onMounted, useTemplateRef, watch } from 'vue'
import { cn } from '../../utils'
import { useMessageScrollerRegister } from './useMessageScroller'

const props = withDefaults(defineProps<NMessageScrollerItemProps>(), {
  scrollAnchor: false,
})

const register = useMessageScrollerRegister()

const itemEl = useTemplateRef<HTMLElement>('item')

onMounted(() => {
  if (props.messageId && itemEl.value)
    register(props.messageId, itemEl.value, null)
})

watch(() => props.messageId, (messageId, previousMessageId) => {
  const element = itemEl.value
  if (!element)
    return
  if (previousMessageId)
    register(previousMessageId, null, element)
  if (messageId)
    register(messageId, element, null)
})

onBeforeUnmount(() => {
  if (props.messageId && itemEl.value)
    register(props.messageId, null, itemEl.value)
})
</script>

<template>
  <div
    ref="item"
    data-slot="message-scroller-item"
    :data-message-id="messageId"
    :data-scroll-anchor="scrollAnchor ? 'true' : 'false'"
    :class="cn(
      'message-scroller-item',
      props.una?.messageScrollerItem,
      props.class,
    )"
  >
    <slot />
  </div>
</template>

<script setup lang="ts">
import type { NMessageScrollerButtonProps } from '../../types'
import { reactiveOmit } from '@vueuse/core'
import { computed } from 'vue'
import { cn } from '../../utils'
import Button from '../elements/Button.vue'
import { useMessageScroller, useMessageScrollerScrollable } from './useMessageScroller'

const props = withDefaults(defineProps<NMessageScrollerButtonProps>(), {
  direction: 'end',
  behavior: 'smooth',
  btn: 'outline-white',
  label: 'i-lucide-arrow-down',
  icon: true,
  // explicit: a boolean-typed prop left absent arrives as `false`, not `undefined`,
  // so Button's `square ?? !!icon` fallback never fires through a wrapper.
  square: true,
  size: 'xs',
})

const delegatedProps = reactiveOmit(props, ['class', 'una', 'ariaLabel', 'direction', 'behavior'])

const { scrollToEnd, scrollToStart } = useMessageScroller()
const scrollable = useMessageScrollerScrollable()

const active = computed(() =>
  props.direction === 'start' ? scrollable.value.start : scrollable.value.end)

const ariaLabel = computed(() =>
  props.ariaLabel ?? (props.direction === 'start' ? 'Scroll to start' : 'Scroll to end'))

function onClick(event: MouseEvent) {
  if (!active.value)
    return
  const target = event.currentTarget as HTMLElement | null
  target?.blur()
  if (event.defaultPrevented)
    return
  if (props.direction === 'start')
    scrollToStart({ behavior: props.behavior })
  else
    scrollToEnd({ behavior: props.behavior })
}
</script>

<template>
  <Button
    v-bind="delegatedProps"
    data-slot="message-scroller-button"
    :data-direction="direction"
    :data-active="active ? 'true' : 'false'"
    :aria-label="ariaLabel"
    :inert="!active"
    :tabindex="active ? undefined : -1"
    :una="props.una"
    :class="cn(
      'message-scroller-button',
      props.una?.messageScrollerButton,
      props.class,
    )"
    @click="onClick"
  >
    <slot />
  </Button>
</template>