useScrollPosition

Tracks the scroll position of a window, document, or element. It updates on scroll events and when the resolved target changes.

In non-browser environments the composable returns zeroed refs and does not register listeners.

Importing

import { useScrollPosition } from '@almighty-shogun/common';

Usage

<template>
    <main ref="content">
        <p>Scrolled {{ scrollY }} pixels</p>
    </main>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useScrollPosition } from '@almighty-shogun/common';

const content = ref<HTMLElement | null>(null);
const { scrollY } = useScrollPosition(content);
</script>

Parameters

target?: MaybeRefOrGetter<NullableOrUndefinable<ComponentTarget>>
Scrollable element, window, document, or Vue component instance to observe. When omitted, the document is observed.

Returns

scrollX: Ref<number>
Current horizontal scroll position.

scrollY: Ref<number>
Current vertical scroll position.

Uses

• HTMLTarget
• NullableOrUndefinable
• unwrapTarget
• useEventListener

Type signature

declare function useScrollPosition(
    target?: MaybeRefOrGetter<NullableOrUndefinable<ComponentTarget>>
): UseScrollPosition;

type ComponentTarget = HTMLTarget | ComponentPublicInstance;
type UseScrollPosition = {
    readonly scrollX: Ref<number>;
    readonly scrollY: Ref<number>;
};