ScrollBar
A pixel-style scrollbar component, based on OverlayScrollbars.
Scroll Container
Use the ScrollBar component to wrap your content inside a scrollbar. You may need to set height styles.
Pass scrollOffset as the scrollbar offset. Providing scrollOffset puts it in controlled mode. Not providing it or setting it to undefined puts it in uncontrolled mode, where you can pass the defaultScrollOffset property as the default value.
Updates to scrollOffset are debounced and only trigger when scrolling stops. If you need to listen for scrolling, listen to the scroll event.
For the ScrollBar component, after obtaining its DOM element, you can access properties like scrollBy, scrollTo, scrollTop, scrollLeft, etc., just like a native element.
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles
And by opposing end them. To die—to sleep,
No more; and by a sleep to say we end
The heart-ache and the thousand natural shocks
That flesh is heir to: 'tis a consummation
Devoutly to be wish'd. To die, to sleep;
To sleep, perchance to dream—ay, there's the rub:
For in that sleep of death what dreams may come,
When we have shuffled off this mortal coil,
Must give us pause—there's the respect
That makes calamity of so long life.
Scrollbar Styles
The scrollbar currently has two style variants: pixel-style ('pixel', default) and simple mode ('simple'), set via variant.
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Loooooooooooooooong text
Functional Usage
Use the useScrollBar hook to manually add a pixel-style scrollbar to a specific area. Add the attribute data-overlayscrollbars-initialize to the element that needs the scrollbar to prevent flickering issues.
And now I'll do't. And so he goes to heaven;
And so am I revenged. That would be scann'd:
A villain kills my father; and for that,
I, his sole son, do this same villain send
To heaven.
O, this is hire and salary, not revenge.
He took my father grossly, full of bread;
With all his crimes broad blown, as flush as May;
And how his audit stands who knows save heaven?
But in our circumstance and course of thought,
'Tis heavy with him: and am I then revenged,
To take him in the purging of his soul,
When he is fit and season'd for his passage?
No!
Up, sword; and know thou a more horrid bent:
When he is drunk asleep, or in his rage,
Or in the incestuous pleasure of his bed;
At gaming, swearing, or about some act
That has no relish of salvation in't;
Then trip him, that his heels may kick at heaven,
And that his soul may be as damn'd and black
As hell, whereto it goes. My mother stays:
This physic but prolongs thy sickly days.
This way, you can add a scrollbar to the <body> element. You can then normally access native properties like window.scrollX, window.scrollY, window.scroll, window.scrollTo, window.scrollBy, etc.
To prevent flickering, add the data-overlayscrollbars-initialize attribute to both <html> and <body>.
import { useScrollBar } from '@pixelium/web-vue'
// If on-demand import
// import { useScrollBar } from '@pixelium/web-vue/es'
const [init] = useScrollBar()
init({
target: document.body
})2
3
4
5
6
7
8
9
10
API
If it doesn't meet your needs, you can refer to the OverlayScrollbars documentation for usage details.
The pixel-style scrollbar themes are named 'pixel-scrollbar-theme' (corresponding to theme="pixel") and 'simple-scrollbar-theme' (corresponding to theme="simple"). After importing the full styles or manually importing @pixelium/web-vue/es/scroll-bar/index.css, you can use it with OverlayScrollbars.
ScrollBarProps
| Attribute | Type | Optional | Default | Description | Version |
|---|---|---|---|---|---|
| scrollOffset | { left?: number; top?: number } | null | True | | Scroll offset, controlled mode, supports v-model. | 0.1.0 |
| defaultScrollOffset | { left?: number; top?: number } | null | True | | Default value for scroll offset, uncontrolled mode. | 0.1.0 |
| variant | 'pixel' | 'simple' | True | 'pixel' | The style variant of the scrollbar. | 0.1.0 |
| showScrollPadding | boolean | True | true | Whether to add padding on the side where the scrollbar appears. | 0.1.0 |
| ghost | boolean | True | false | 0.1.0 | |
| edgeMask | boolean | True | false | Edge mask. When content is scrollable, displays a mask overlay at the edges of the scroll container to indicate there is more content to scroll. Accepts true (show masks on all four sides), false (hide masks), or an array of up to 4 booleans (controlling each side in [top, right, bottom, left] order). The array length rules follow CSS padding shorthand, supporting 1 to 4 values. | 0.2.0 |
| visible | boolean | True | true | Whether the scrollbar is visible. Defaults to true. Set to false to hide the scrollbar while keeping the content scrollable. | 0.2.0 |
ScrollBarEvents
| Event | Parameter | Description | Version |
|---|---|---|---|
| update:scrollOffset | value: { left: number; top: number } | Callback when scrollOffset updates. | 0.1.0 |
| initialize | instance: OverlayScrollbars | Callback when the scrollbar initializes. Receives an OverlayScrollbars instance as the parameter. For specific details, refer to the OverlayScrollbars documentation. | 0.1.0 |
| update | | Callback when the scrollbar updates. | 0.1.0 |
| scroll | event: Event | Callback when scrolling occurs. | 0.1.0 |
ScrollBarSlots
| Slot | Parameter | Description | Version |
|---|---|---|---|
| default | | Content of the scroll container. | 0.1.0 |
ScrollBarExpose
| Attribute | Type | Optional | Default | Description | Version |
|---|---|---|---|---|---|
| scrollTo | { (options?: ScrollToOptions): void; (x: number, y: number): void } | False | | Same behavior as native scrollTo. | 0.1.0 |
| scrollBy | { (options?: ScrollToOptions): void; (x: number, y: number): void } | False | | Same behavior as native scrollBy. | 0.1.0 |
| scrollHeight | number | False | | 0.2.0 | |
| scrollWidth | number | False | | 0.2.0 | |
| scrollTop | number | False | | 0.2.0 | |
| scrollLeft | number | False | | 0.2.0 |
useScrollBar
import { type UseOverlayScrollbarsInitialization, type UseOverlayScrollbarsInstance } from 'overlayscrollbars-vue'
const useScrollBar: (variant?: "pixel" | "simple") => readonly [UseOverlayScrollbarsInitialization, UseOverlayScrollbarsInstance, Ref<boolean, boolean>]2
3