BackTop 맨 위로

스크롤이 임계값을 넘으면 나타나고 클릭 시 맨 위로 돌아갑니다. 부드러운 스크롤은 네이티브 scrollTo({ behavior: 'smooth' })를 사용하며, prefers-reduced-motion 환경에서는 자동으로 전환됩니다.

기본 사용법

기본 사용법(아래로 스크롤해 보세요)

<script setup lang="ts">
</script>

<template>
  <!-- 기본 사용법 -->
  <LhBackTop :right="24" :bottom="24" />
</template>

<script>
export default {}
</script>

<template>
  <!-- 기본 사용법 -->
  <LhBackTop :right="24" :bottom="24" />
</template>

visibility-height로 나타나는 임계값을 지정하고, smooth로 부드러운 스크롤을 끄고, target으로 특정 스크롤 컨테이너를 감시합니다.

커스텀 임계값과 부드러운 스크롤 끄기

<script setup lang="ts">
</script>

<template>
  <!-- 커스텀 임계값과 부드러운 스크롤 끄기 -->
  <LhBackTop :visibility-height="80" :smooth="false" :right="24" :bottom="90" />
</template>

<script>
export default {}
</script>

<template>
  <!-- 커스텀 임계값과 부드러운 스크롤 끄기 -->
  <LhBackTop :visibility-height="80" :smooth="false" :right="24" :bottom="90" />
</template>

스크롤 정지(scrollend)

@scrollend는 스크롤이 정지할 때 현재 스크롤 거리를 전달합니다. 네이티브 scrollend 이벤트를 우선 사용하며(Chromium 114+ / Safari 18.2+), 구형 브라우저에서는 자동으로 scroll + 150ms 디바운스로 폴백합니다. 앵커 연동, 데이터 지연 로딩 등에 자주 사용됩니다.

scrollend 이벤트

마지막으로 정지한 위치: (스크롤 안 함)

<script setup>
import { ref } from 'vue'

const lastStop = ref('(스크롤 안 함)')

function onScrollEnd(scrollTop) {
  lastStop.value = `${scrollTop}px`
}
</script>

<template>
  <LhBackTop :right="24" :bottom="160" @scrollend="onScrollEnd" />
</template>

<script>
export default {
  data() {
    return { lastStop: '(스크롤 안 함)' }
  },
  methods: {
    onScrollEnd(scrollTop) {
      this.lastStop = `${scrollTop}px`
    },
  },
}
</script>

<template>
  <LhBackTop :right="24" :bottom="160" @scrollend="onScrollEnd" />
</template>

API

LhBackTop Props

속성	설명	타입	기본값
target	스크롤 컨테이너(선택자 또는 요소, 기본값 뷰포트)	string | HTMLElement	—
visibilityHeight	스크롤이 지정한 픽셀을 넘으면 나타남	number	200
right	오른쪽 오프셋 px	number	40
bottom	하단 오프셋 px	number	40
smooth	부드러운 스크롤 여부	boolean	true
sx	sx 빠른 레이아웃 속성	LhSxProps	—

Events

이벤트	설명	콜백 매개변수
click	버튼 클릭 시 발생(이후 맨 위로 스크롤 실행)	(event: MouseEvent)
scrollend	스크롤 정지 시 발생, 현재 스크롤 거리를 전달	(scrollTop: number)

슬롯: default(커스텀 내용).

접근성

• 실제 <button>이며, 아이콘 전용 형태는 반드시 이름을 지정해야 합니다(언어 팩 backtop.label)
• 나타나거나 사라질 때 포커스 트리 충돌이 발생하지 않습니다(숨길 때 v-if로 제거)

타입 정의

이 컴포넌트가 외부로 내보내는 TypeScript 타입 구조는 다음과 같습니다(packages/components/backtop/src/types.ts와 @lh-ui/share/core/* 소스에서 자동 추출, 각 항목을 펼쳐 전체 정의를 확인하세요. 속성 설명은 위쪽 Props 표를 참고하세요).

LhBackTopProps

export interface LhBackTopProps {
  /** 스크롤 컨테이너(선택자 또는 요소, 기본값 뷰포트) */
  target?: string | HTMLElement
  /** 스크롤이 지정한 픽셀을 넘으면 나타남 */
  visibilityHeight?: number
  /** 오른쪽 오프셋 px */
  right?: number
  /** 하단 오프셋 px */
  bottom?: number
  /** 부드러운 스크롤 여부 */
  smooth?: boolean
  /** sx 빠른 레이아웃 속성 */
  sx?: LhSxProps
}

상수

이 컴포넌트에서 사용하는 공개 상수는 다음과 같습니다(Props 표의 '타입 / 기본값' 열에서 같은 이름의 항목을 클릭하면 이곳으로 이동합니다).

LH_BACKTOP_VISIBILITY_HEIGHT_DEFAULT _{(@lh-ui/share/core/backtop에서 가져옴)}

/** 기본 스크롤 임계값 px */
export const LH_BACKTOP_VISIBILITY_HEIGHT_DEFAULT = 200

LH_BACKTOP_SCROLLEND_DELAY _{(@lh-ui/share/core/backtop에서 가져옴)}

/** scrollend 디바운스 폴백의 정지 임계값 ms(네이티브 scrollend를 지원하지 않는 브라우저에서만 사용) */
export const LH_BACKTOP_SCROLLEND_DELAY = 150