Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bespoyasov/scroller
Fast, light-weight (4KB gzip), and dependency-free content scroller.
https://github.com/bespoyasov/scroller
component dependency-free drag-and-drop javascript scroller ui
Last synced: 15 days ago
JSON representation
Fast, light-weight (4KB gzip), and dependency-free content scroller.
- Host: GitHub
- URL: https://github.com/bespoyasov/scroller
- Owner: bespoyasov
- License: mit
- Created: 2015-03-30T18:38:24.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2023-11-04T13:41:12.000Z (about 1 year ago)
- Last Synced: 2024-12-06T02:43:05.449Z (28 days ago)
- Topics: component, dependency-free, drag-and-drop, javascript, scroller, ui
- Language: JavaScript
- Homepage:
- Size: 2.87 MB
- Stars: 123
- Watchers: 4
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Scroller
Fast, light-weight (4KB gzip), and dependency-free content scroller.
https://user-images.githubusercontent.com/9102374/170833443-b9428466-a9fd-48e5-b18b-4c4089137dd5.mp4
For more examples of how it works with different settings and UI conditions, check out [this link](https://bespoyasov.ru/scroller/example/).
## Installation
Install Scroller with npm:
```shell
npm install prokrutchik
```
Add the scripts and styles to your project:
```js
import { Scroller } from "prokrutchik";
import "prokrutchik/styles.css";
```
Or add them directly to the HTML file:
```html
```
## Initialization
By default, Scroller provides auto initialization for all the `.scroller` elements on the page:
```html
- First item
- Second item
- Third item
```
You can also initialize the instance manually:
```html
- First item
- Second item
- Third item
import { Scroller } from "prokrutchik";
const instance = new Scroller({
element: document.querySelector(".foo"),
});
```
## Configuration
You can configure Scroller via `data-` attributes in HTML:
- `data-navigation`, shows/hides the navigation buttons, `"visible" | "hidden"`;
- `data-scrollbar`, shows/hides the scrollbar under the content, `"visible" | "hidden"`;
- `data-align`, specifies how to align the content if it fits the screen, `"start" | "center" | "end"`;
- `data-start-position`, initial position of the content, `number of px | "start" | "center" | "end"`;
- `data-start-duration`, starting animation duration, `number of milliseconds`.
Scroller items can be configured with:
- `data-anchor`, label of the item in the navigation, `string`;
- `data-focused`, if defined, Scroller will scroll to this item at the start.
### Using JavaScript
You can also configure Scroller using the config object:
```js
const scroller = new Scroller({
element: document.querySelector(".foo"),
// Show/hide the scrollbar, "visible" | "hidden":
scrollbar: "hidden",
// Show/hide the navigation, "visible" | "hidden":
navigation: "hidden",
// How to align content if it fits the screen, "start" | "center" | "end":
align: "center",
// Initial scroller content position, "start" | "center" | "end" | number of px:
startPosition: "center",
// Starting animation duration, number of milliseconds:
startDuration: 500,
});
```
## Public API
Scroller provides API for changing current position, handling item clicks, and dynamically updating the config.
### Position Change
For position change, use the `scrollTo` method:
```js
// Scrolls to the beginning of the content
scroller.scrollTo("start");
// Scrolls to the center of the content:
scroller.scrollTo("center");
// Scrolls to the end of the content:
scroller.scrollTo("end");
// Scrolls to 100px from the start of the content:
scroller.scrollTo(100);
// Second optional parameter specifies
// the animation duration in milliseconds.
// Scrolls to center in 500 ms:
scroller.scrollTo("center", 500);
```
### Item Click Callback
For handling clicks on items, specify the `onItemClick` handler in the config:
```js
const scroller = new Scroller({
element: document.querySelector(".foo"),
onItemClick: (event) => {
/* The `event` argument here is `TouchEvent` or `MouseEvent` depending on the user device. */
},
});
```
### Config Updates
For configuration updates, use the `update` method:
```js
scroller.update({
scrollbar: "hidden",
navigation: "hidden",
align: "center",
onItemClick: someFunc,
});
```
## Examples
Scroller with disabled scrollbar, active navigation, and start alignment, configured via HTML data-attributes:
```html
```
Scroller with the same settings configured via config object:
```js
import { Scroller } from "prokrutchik";
import "prokrutchik/styles.css";
const myScroller = new Scroller({
el: document.querySelector(".foo"),
scrollbar: "hidden",
align: "start",
});
```
## Components
If you want to use Scroller with React or Vue, check out these packages:
- [React Scroller](https://github.com/bespoyasov/react-scroller)
- [Vue Scroller](https://github.com/bespoyasov/vue-scroller)