A lightweight jQuery custom scrollbar plugin, that triggers event when reached the defined point.
- Browser compatibility
- Installation
- Usage
- Basic features
- Infinite scrolling implementation example
- License
- IE 7+
- Firefox
- Opera (old and new)
- Safari
- Chrome
- Chrome for Android
... and others.
Scrollbox is automatically tested on the following browsers
Several quick start options are available:
- Download the latest release.
- Clone the repo:
git clone https://github.com/Invis1ble/scrollbox.git
. - Install with Bower:
bower install scrollbox
. - Install with npm:
npm install scrollbox
. - Install with Composer:
composer require invis1ble/scrollbox
.
After installing the plugin you have to install jquery-mousewheel. You can simply download it as archive and unpack to desired location.
In order to use the plugin, you have to include styles and script to your html e.g.:
<link href="/path/to/scrollbox.min.css" media="screen" rel="stylesheet" type="text/css">
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="/path/to/jquery.mousewheel.min.js" type="text/javascript"></script>
<script src="/path/to/scrollbox.min.js" type="text/javascript"></script>
Let's assume that you want to stylize the following element:
<div id="long-content-container">
Here is a long content
</div>
Then you should define max-height
and/or max-width
of that element:
#long-content-container {
max-height: 200px;
max-width: 200px;
}
and initialize Scrollbox:
$('#long-content-container').scrollbox();
That's all.
Now if real size of the container is greater than the specified max-height
/max-width
then the plugin will add scrollbar to it.
You can stylize scrollbar via css
or even better by overwriting corresponding less
variables.
See src/less/ for more details.
Scrollbox uses several options to configuring behavior. The default options are:
{
distanceToReach: {
x: 0,
y: 0
},
wheelSensitivity: 20,
momentum: {
acceleration: 1600,
thresholdTime: 500
},
startAt: {
x: 'left',
y: 'top'
},
templates: {
horizontalBar: '<div></div>',
verticalBar: '<div></div>',
horizontalRail: '<div></div>',
verticalRail: '<div></div>',
wrapper: '<div></div>'
}
}
You can optionally pass an object containing all of the options that you would like to initialize Scrollbox with e.g.:
$('#long-content-container').scrollbox({
wheelSensitivity: 25,
startAt: {
y: 'bottom'
}
});
or re-define default values for all instances:
$.fn.scrollbox.Constructor.getDefault().distanceToReach.y = 100;
The initial position of the scroll on x-axis.
The value can be 'left'
, 'right'
or number of pixels from the left boundary.
The initial position of the scroll on y-axis.
The value can be 'top'
, 'bottom'
or number of pixels from the top boundary.
The distance from the left and right boundaries of the content when reachleft.scrollbox
and reachright.scrollbox
events should be triggered.
This option is useful when you want to implement so-called "infinite scrolling".
The distance from the top and bottom boundaries of the content when reachleft.scrollbox
and reachright.scrollbox
events should be triggered.
This option is useful when you want to implement so-called "infinite scrolling".
The distance in pixels for one fixed step of mouse wheel.
You probably shouldn't change this value.
Swipe acceleration factor.
Threshold time in milliseconds for detect inertial moving at swipe.
Normally you don't need to change this templates, but you can if you want.
You can call some methods of the plugin.
Recalculates scrollbars' positions and sizes.
For example, If you write the infinite scroll implementation you have to update scrollbar position and size after content has been added.
To do this you should simply call .update()
method:
$('#long-content-container').scrollbox('update');
Scrolls by pixels.
See .animate() for the available values of the animationOptions
Example:
$('#long-content-container').scrollbox('scrollBy', 100, 200);
If you want to scroll only on y-axis you can pass 0
as deltaX
value:
$('#long-content-container').scrollbox('scrollBy', 0, 200);
Scrolls to specified position.
x
can be integer (pixels), or string 'left'
or 'right'
.
y
also can be integer (pixels), or string 'top'
or 'bottom'
.
'left'
, 'right'
, 'top'
and 'bottom'
means the boundaries.
See .animate() for the available values of the animationOptions
Example:
$('#long-content-container').scrollbox('scrollTo', 100, 200);
If you want to scroll only on y-axis you can pass undefined
as x
value:
$('#long-content-container').scrollbox('scrollTo', undefined, 'bottom');
Completely removes all stuff from the element.
Scrollbox triggers a several events during lifecycle.
Triggered when scrolling reach the left boundary of the content. Respects distanceToReach.x
option.
Triggered when scrolling reach the right boundary of the content. Respects distanceToReach.x
option.
Triggered when scrolling reach the top boundary of the content. Respects distanceToReach.y
option.
Triggered when scrolling reach the bottom boundary of the content. Respects distanceToReach.y
option.
var $container = $('#content-container');
$container
.on('reachbottom.scrollbox', function () {
$.ajax({
// options
}).done(function (response) {
$container
.append(response)
.scrollbox('update');
});
})
.scrollbox({
distanceToReach: {
y: 100
}
});