Scrollbar Component
Scrollbar replaces native browser scrollbars with customizable alternatives.
When to Use
- Custom scrollbar styling
- Scrollable containers
- Infinite scrolling
- Custom scroll areas
Basic Usage
<template>
<el-scrollbar height="400px">
<p v-for="item in 20" :key="item">{{ item }}</p>
</el-scrollbar>
</template>
Horizontal Scroll
<template>
<el-scrollbar>
<div style="display: flex; width: 1000px;">
<div v-for="item in 20" :key="item" style="width: 100px;">{{ item }}</div>
</div>
</el-scrollbar>
</template>
Max Height
<template>
<el-scrollbar max-height="400px">
<p v-for="item in 50" :key="item">{{ item }}</p>
</el-scrollbar>
</template>
Manual Scroll
<template>
<el-scrollbar ref="scrollbarRef" height="400px">
<p v-for="item in 100" :key="item">{{ item }}</p>
</el-scrollbar>
<el-button @click="scrollToTop">Scroll to Top</el-button>
</template>
<script setup>
import { ref } from 'vue'
const scrollbarRef = ref()
const scrollToTop = () => {
scrollbarRef.value.setScrollTop(0)
}
</script>
Infinite Scroll
<template>
<el-scrollbar height="400px" @end-reached="loadMore">
<p v-for="item in items" :key="item">{{ item }}</p>
</el-scrollbar>
</template>
<script setup>
import { ref } from 'vue'
const items = ref(Array.from({ length: 20 }, (_, i) => i + 1))
const loadMore = (direction) => {
if (direction === 'bottom') {
const newItems = Array.from({ length: 10 }, (_, i) => items.value.length + i + 1)
items.value.push(...newItems)
}
}
</script>
Always Visible
<template>
<el-scrollbar height="400px" always>
<p v-for="item in 50" :key="item">{{ item }}</p>
</el-scrollbar>
</template>
API Reference
Attributes
| Name |
Description |
Type |
Default |
| height |
Scrollbar height |
string | number |
— |
| max-height |
Max height |
string | number |
— |
| native |
Use native scrollbar |
boolean |
false |
| wrap-style |
Wrap container style |
string | CSSProperties |
— |
| wrap-class |
Wrap container class |
string |
— |
| view-style |
View style |
string | CSSProperties |
— |
| view-class |
View class |
string |
— |
| noresize |
Ignore container size changes |
boolean |
false |
| tag |
View element tag |
string |
'div' |
| always |
Always show scrollbar |
boolean |
false |
| min-size |
Minimum scrollbar size |
number |
20 |
| distance |
Distance to trigger end-reached |
number |
0 |
Events
| Name |
Description |
Type |
| scroll |
Triggers on scroll |
({ scrollLeft, scrollTop }) => void |
| end-reached |
Triggers at scroll end |
(direction: 'top' | 'bottom' | 'left' | 'right') => void |
Slots
| Name |
Description |
| default |
Scrollable content |
Exposes
| Name |
Description |
Type |
| scrollTo |
Scroll to position |
(options: ScrollToOptions | number, yCoord?: number) => void |
| setScrollTop |
Set scroll top |
(scrollTop: number) => void |
| setScrollLeft |
Set scroll left |
(scrollLeft: number) => void |
| update |
Update scrollbar state |
() => void |
| wrapRef |
Wrap element ref |
Ref<HTMLDivElement> |
Best Practices
- Use
height for fixed-height containers
- Use
max-height for flexible containers
- Use
always for better visibility on touch devices
- Use
end-reached for infinite scrolling
jiaiyan