Scrollbar ​

Used to replace the browser's native scrollbar.

Basic usage ​

Use height property to set the height of the scrollbar, or if not set, it adapts according to the parent container height.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

Horizontal scroll ​

When the element width is greater than the scrollbar width, the horizontal scrollbar is displayed.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

Scroll masks 2.14.8 ​

Use mask to indicate that more content can be scrolled to above, below, to the left, or to the right of the viewport. Masks are disabled by default.

ValueBehavior
falseDisable all masks (default).
trueEnable all four masks, according to the available overflow.
'top'Enable only the top mask.
'bottom'Enable only the bottom mask.
'left'Enable only the left mask.
'right'Enable only the right mask.
vue
<template>
  <el-scrollbar height="240px" mask />
  <el-scrollbar height="240px" mask="top" />
  <el-scrollbar height="240px" mask="bottom" />
  <el-scrollbar mask="left" />
  <el-scrollbar mask="right" />
</template>

Scroll vertically or horizontally and change the mask mode. Each enabled mask appears only while there is more content in its direction. It disappears when that edge is reached. Masks stay hidden on axes without overflow; when both axes overflow, all four masks can appear together.

Vertical scrolling

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

Horizontal scrolling

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

Masks fade in and out over 200ms by default, using --el-transition-duration-fast. The animation is disabled when the user prefers reduced motion. Masks do not block pointer events or cover scrollbar controls, and also work with native.

left and right refer to the physical edges of the viewport, including when the scroll container uses direction: rtl.

The distance attribute only affects the end-reached event; it does not change when masks appear. When using noresize, call update() after changing the content or container size to refresh the masks.

Customize masks ​

Use the following CSS variables on the Scrollbar component to customize each mask:

CSS variableDescriptionDefault
--el-scrollbar-top-mask-heightHeight of the top mask.40px
--el-scrollbar-bottom-mask-heightHeight of the bottom mask.40px
--el-scrollbar-left-mask-widthWidth of the left mask.40px
--el-scrollbar-right-mask-widthWidth of the right mask.40px
--el-scrollbar-top-mask-colorColor of the top mask.var(--el-bg-color)
--el-scrollbar-bottom-mask-colorColor of the bottom mask.var(--el-bg-color)
--el-scrollbar-left-mask-colorColor of the left mask.var(--el-bg-color)
--el-scrollbar-right-mask-colorColor of the right mask.var(--el-bg-color)

The default color follows the light or dark theme. Set the mask colors to match the container background when using a custom background. The example above sets the vertical mask heights and horizontal mask widths to 48px.

Max height ​

The scrollbar is displayed only when the element height exceeds the max height.

1

2

3

Manual scroll ​

Use setScrollTop and setScrollLeft methods can control scrollbar manually.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

Infinite scroll 2.10.0 ​

end-reached is triggered when the scrollbar reaches the end. It can be used as an infinite scroll.

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

API ​

Attributes ​

NameDescriptionTypeDefault
heightheight of scrollbarstring / number—
max-heightmax height of scrollbarstring / number—
nativewhether to use the native scrollbar stylebooleanfalse
wrap-stylestyle of wrap containerstring / object—
wrap-classclass of wrap containerstring—
view-stylestyle of viewstring / object—
view-classclass of viewstring—
noresizedo not respond to container size changes, if the container size does not change, it is better to set it to optimize performancebooleanfalse
tagelement tag of the viewstringdiv
alwaysalways show scrollbarbooleanfalse
mask 2.14.8Gradient masks: true for all edges, a direction for one edge, and false to disableboolean / enumfalse
min-sizeminimum size of scrollbarnumber20
id 2.4.0id of viewstring—
role 2.4.0 a11yrole of viewstring—
aria-label 2.4.0 a11yaria-label of viewstring—
aria-orientation 2.4.0 a11yaria-orientation of viewenum—
tabindex 2.8.3tabindex of wrap containernumber / string—
distance 2.10.5trigger end-reached event distance(px)number0

Events ​

NameDescriptionType
scrolltriggers when scrolling, return distance of scrollingFunction
end-reached 2.10.0triggers when the end of a scroll is triggeredFunction

Slots ​

NameDescription
defaultcustomize default content

Exposes ​

NameDescriptionType
handleScrollhandle scroll eventFunction
scrollToscrolls to a particular set of coordinatesFunction
setScrollTopSet distance to scroll topFunction
setScrollLeftSet distance to scroll leftFunction
updateupdate scrollbar state manuallyFunction
wrapRefscrollbar wrap refobject

Source ​

Component • Style • Docs

Contributors ​