https://github.com/matb85/modular-slider
A dependency-free slider with no DOM manipulations!
https://github.com/matb85/modular-slider
carousel carousel-component carousel-plugin carousel-slider dependency-free javascript slider slider-component sliders slideshow svelte sveltejs typescript vite vue vue3
Last synced: 3 months ago
JSON representation
A dependency-free slider with no DOM manipulations!
- Host: GitHub
- URL: https://github.com/matb85/modular-slider
- Owner: Matb85
- License: isc
- Created: 2021-03-23T11:44:40.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-02-09T23:14:41.000Z (5 months ago)
- Last Synced: 2025-04-23T02:48:53.480Z (3 months ago)
- Topics: carousel, carousel-component, carousel-plugin, carousel-slider, dependency-free, javascript, slider, slider-component, sliders, slideshow, svelte, sveltejs, typescript, vite, vue, vue3
- Language: TypeScript
- Homepage: https://matb85.github.io/modular-slider/
- Size: 5.46 MB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Modular Slider
## A dependency-free slider with NO DOM manipulations, written in Typescript
### [Check out the demos here](https://matb85.github.io/modular-slider/)
Modular Slider aims to deliver just what you want, while using the best of EcmaScript goodies. Here are some of its features:
- :label: written in Typescript and ESM
- :zap: relies on promises, async/await and event listeners
- :art: modular architecture - optimized for tree-shaking, weighs nothing in your final build
- :fire: absolutely no DOM manipulations - no removing, adding or cloning nodes, just class and style attribute tweaks
- :rocket: works perfectly with any frontend framework - does not break down v-dom thanks to no DOM manipulations
- :boom: supports SSR - tested in [Nuxt.js](https://nuxt.com/) & [SvelteKit](https://svelte.dev/)
**This package ships as an esm module only.**
## Architecture
Modular Slider consists of **_base classes_** and **_plugins_**:
### Base classes
Base classes provide basic functionalities of the slider. Their names are **PascalCase**. currently, there are 3 mixins:
- Carousel - provides methods for a carousel slider (with a loop)
- NoLoop - provides methods for a basic slider
- SliderBase - an abstract class, not a ready-to-use slider, provides basic methods for creating your own slider
### Plugins
Plugins are functions that enrich your slider with non-critical features. Their names are all **camelCase**. Here are the currently available plugins:
- swipeHandler - provides event handling - **compulsory if you want to drag the slider with mouse/touch**
- buttons - adds next/previous slide buttons
- pagination - adds pagination
- autoplay - adds autoplay
- duplicate - useful for Carousels, makes sure that there are no fewer sliders than the set number of slides per view + 2 which is required for the loop
- lazyLoading - enables lazy loading images in the slider, loads image's srcset when the slide is in view
## Usage
First of all download the package:
```bash
$ npm i modular-slider
$ pnpm i modular-slider
$ yarn add modular-slider
$ bun install modular-slider
$ deno install npm:modular-slider
```
Once you've done that, take a look at an example setup:
1. Add markup:
- outer **container** with **id** and **.MS-wrapper** class
- inner **container** with **.MS-con** class
- some **slides inside** - no classes required
```html
- 1
- 2
- 3
- 4
- 5
- 6
prev
next
```
2. import css from "modular-slider/dist/modular-slider.css" and follow [**one of the available options**](#css-options). This example uses the default option
```scss
@import "modular-slider/dist/modular-slider.css";
.your-slider-class {
--number-of-slides: 6; // the number of the slides, total
--slides-per-view: 2; // the number of how many slides are displayed at once
// your css...
}
```
3. Add js
```js
import { Carousel, swipeHandler, lazyLoading } from "modular-slider";
new Carousel({
container: "your-slider-id", // id of the inner container
initialSlide: 1, // optional, default is 0
plugins: [
// enables dragging the slider with mouse/touch
swipeHandler(),
// the button plugin uses the querySelector method, hence # at the beginning
buttons({ nextBtn: "#next", prevBtn: "#prev" })
],
});
```
**[You can find more examples here](https://matb85.github.io/modular-slider/)**
## CSS options
By default, modular slider provides two css options. They both require some css variables that you may put either in the **:root** or **.MS-wrapper** element.
1. Width in percentage (default)
the outer container has a specified width and the slides subordinate to it
> e.g. the container has width set to **30rem** or **80%** whereas slides have width set to **50%**
```scss
.your-slider-class.MS-wrapper {
// you DON'T have to set --number-of-slides - it's just a fallback value just in case something goes wrong
--number-of-slides: 6; // the number of the slides, total
--slides-per-view: 2; // the number of how many slides are displayed at once
--slide-margin: 25px; // the left and right margin of each element
width: 80%; // add some width
}
```
2. Fixed width (add **.MS-fixed** class)
the slides have a specified width - the container subordinates to them
> e.g. the container **does not** have a set width whereas slides have width set to **15rem**
```scss
.your-slider-class.MS-fixed.MS-wrapper {
--slide-width: 15rem; // the width of each slide
--slide-margin: 25px; // the left and right margin of each element
--slides-per-view: 2; // the number of how many slides are displayed at once
// don't specify the width - it will be calculated based on the variables above
}
```
**By default --slide-margin is set to 0px.**
## Contributing
Modular Slider by design encourages users to enhance it. Don't like the event handlers? Want the buttons/pagination to automatically generate themselves? Write a plugin that will do that. If you have created such an improvement, fell free to share it. PRs are welcome! :fire:
## [Changelog](https://github.com/Matb85/modular-slider/blob/master/CHANGELOG.md)
## [License](https://github.com/Matb85/modular-slider/blob/master/LICENSE.txt)