@twistedandy/better-carousel 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +838 -2
- package/dist/better-carousel.css +1 -0
- package/dist/better-carousel.js +3175 -0
- package/dist/better-carousel.min.js +1 -0
- package/package.json +55 -5
- package/src/index.js +49 -0
- package/src/scripts/autoplay.js +288 -0
- package/src/scripts/carousel.js +834 -0
- package/src/scripts/geometry.js +429 -0
- package/src/scripts/input.js +432 -0
- package/src/scripts/layout.js +205 -0
- package/src/scripts/loop.js +83 -0
- package/src/scripts/markup.js +268 -0
- package/src/scripts/motion.js +232 -0
- package/src/scripts/navigation.js +209 -0
- package/src/scripts/options.js +153 -0
- package/src/styles/better-carousel.scss +323 -0
- package/src/types/better-carousel.d.ts +309 -0
package/README.md
CHANGED
|
@@ -1,3 +1,839 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<a href="https://twistedandy.github.io/better-carousel/"><img src="demo/assets/logo.svg" alt="Better Carousel" width="560" /></a>
|
|
4
|
+
|
|
5
|
+
<p>A small, fast and accessible JavaScript carousel.<br />The CSS sets the layout, and the motion runs on the compositor, also on slow phones.</p>
|
|
6
|
+
|
|
7
|
+
[](dist/better-carousel.min.js)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[](package.json)
|
|
10
|
+
|
|
11
|
+
**[Documentation and live examples](https://twistedandy.github.io/better-carousel/)** · [Issues](https://github.com/TwistedAndy/better-carousel/issues)
|
|
12
|
+
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
|
|
17
|
+
- **Layout from CSS** - Your CSS sets the sizes of the slides, the space between them, the axis and the alignment. One carousel can show 1 slide on a phone and 4 slides on a desktop.
|
|
18
|
+
- **Smooth** - Each motion is a Web Animations API animation of `translate`. No script runs on each frame, also during the auto scroll.
|
|
19
|
+
- **Small** - <!-- generated:gzip -->11.6 KB<!-- /generated --> gzip with loop, autoplay, auto scroll, auto height, sync and the mouse wheel.
|
|
20
|
+
- **Loop** - The loop moves the original slides. It adds clones only if the slides are too few.
|
|
21
|
+
- **Vertical and grid** - A column layout makes a vertical carousel. A CSS grid with more rows also works.
|
|
22
|
+
- **Accessible** - WCAG 2.1 AA: names for the carousel, the slides and the buttons, the keyboard focus, a live region and reduced motion.
|
|
23
|
+
- **Lazy start** - With the `lazy` option, a carousel out of view starts when it comes near the screen.
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
Load the minified script and the stylesheet from jsDelivr. The script adds the global `BetterCarousel` function.
|
|
28
|
+
|
|
29
|
+
```html
|
|
30
|
+
<link
|
|
31
|
+
rel="stylesheet"
|
|
32
|
+
href="https://cdn.jsdelivr.net/gh/TwistedAndy/better-carousel@v1.0.0/dist/better-carousel.css"
|
|
33
|
+
integrity="sha384-3ROtqpAC1ZPhSpDul73SGiTOv1L5kTr/08sUr6FPY6S79RIDi7mpI22ttbuxI/w8"
|
|
34
|
+
crossorigin="anonymous"
|
|
35
|
+
/>
|
|
36
|
+
<script
|
|
37
|
+
src="https://cdn.jsdelivr.net/gh/TwistedAndy/better-carousel@v1.0.0/dist/better-carousel.min.js"
|
|
38
|
+
integrity="sha384-c07capt5gSP/u/29MrkOEgCGW7Igro6cgxxf+xcsoNU8vmYtVkOELryyxkxbLe9i"
|
|
39
|
+
crossorigin="anonymous"
|
|
40
|
+
></script>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Or install the package from npm, and import the script and the stylesheet with a bundler:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
npm install @twistedandy/better-carousel
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
import BetterCarousel from '@twistedandy/better-carousel'
|
|
51
|
+
import '@twistedandy/better-carousel/css'
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
| File | Format | Use |
|
|
55
|
+
| --- | --- | --- |
|
|
56
|
+
| `dist/better-carousel.min.js` | IIFE, minified | For a `script` tag. It adds the global `BetterCarousel` function. |
|
|
57
|
+
| `dist/better-carousel.js` | ES module | For a bundler: `import BetterCarousel from '@twistedandy/better-carousel'`. |
|
|
58
|
+
| `dist/better-carousel.css` | CSS | The styles with the default class names. |
|
|
59
|
+
| `src/types/better-carousel.d.ts` | TypeScript | The types. TypeScript and the editors find them automatically. |
|
|
60
|
+
| `src/styles/better-carousel.scss` | SCSS | The styles with your class names: `@twistedandy/better-carousel/scss`. See [Styling](#styling). |
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
1. Put the slides into a container.
|
|
65
|
+
2. Give the container a flex row with CSS.
|
|
66
|
+
3. Give each slide a width and a right margin.
|
|
67
|
+
4. Start the carousel.
|
|
68
|
+
|
|
69
|
+
```html
|
|
70
|
+
<div class="items carousel">
|
|
71
|
+
<div class="item"><img src="photo-1.jpg" alt="Photo 1" /></div>
|
|
72
|
+
<div class="item"><img src="photo-2.jpg" alt="Photo 2" /></div>
|
|
73
|
+
<div class="item"><img src="photo-3.jpg" alt="Photo 3" /></div>
|
|
74
|
+
<div class="item"><img src="photo-4.jpg" alt="Photo 4" /></div>
|
|
75
|
+
</div>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```css
|
|
79
|
+
/* The negative margin of the container cancels the margin of the last slide in the row */
|
|
80
|
+
.items {
|
|
81
|
+
--gap: 20px;
|
|
82
|
+
display: flex;
|
|
83
|
+
width: calc(100% + var(--gap));
|
|
84
|
+
margin-right: calc(-1 * var(--gap));
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
.items .item {
|
|
88
|
+
flex: none;
|
|
89
|
+
width: calc(100% / 3 - var(--gap));
|
|
90
|
+
margin-right: var(--gap);
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
```js
|
|
95
|
+
// One carousel
|
|
96
|
+
const carousel = BetterCarousel(document.querySelector('.items'))
|
|
97
|
+
|
|
98
|
+
// All carousels on the page
|
|
99
|
+
const carousels = BetterCarousel.initAll('.items.carousel')
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The [documentation](https://twistedandy.github.io/better-carousel/) has live examples: alignment, vertical carousels, grids, free drag, thumbnails, autoplay, auto scroll and auto height.
|
|
103
|
+
|
|
104
|
+
## Concepts
|
|
105
|
+
|
|
106
|
+
The library puts the container into a viewport and a root. Then it adds the arrows and the dots to the root:
|
|
107
|
+
|
|
108
|
+
```html
|
|
109
|
+
<div class="better" role="region" aria-roledescription="carousel" aria-label="Carousel">
|
|
110
|
+
<div class="better_viewport">
|
|
111
|
+
<div class="items carousel better_container">
|
|
112
|
+
<div class="item">...</div>
|
|
113
|
+
</div>
|
|
114
|
+
</div>
|
|
115
|
+
<button class="better_button better_prev" aria-label="Previous slide"></button>
|
|
116
|
+
<button class="better_button better_next" aria-label="Next slide"></button>
|
|
117
|
+
<div class="better_dots">...</div>
|
|
118
|
+
</div>
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
| Term | Meaning |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| Root | The outer element. It holds the viewport, the arrows and the dots. The library adds it if the page does not have it. |
|
|
124
|
+
| Viewport | The element that clips the slides. Its size is the visible area. |
|
|
125
|
+
| Container | The element that moves. Your CSS sets its layout, and the library sets its `translate`. |
|
|
126
|
+
| Slide | A child of the container, or an element that matches the `slides` selector. |
|
|
127
|
+
| Snap | A position where the carousel can stop. A snap shows one slide or a group of slides. |
|
|
128
|
+
| Selected snap | The snap that shows now. `selectedSnap()` gives its index. |
|
|
129
|
+
| Selected slide | The slide at the selected snap. It gets the `selected` class. `selectedSlide()` gives its index. |
|
|
130
|
+
| Clone | A copy of a slide that the loop adds when the slides are too few. Clones are not in `slideNodes()`, and they have no index. |
|
|
131
|
+
| Motion | A change of position with an animation. When a motion stops, the `settle` event occurs. |
|
|
132
|
+
| Fit | All slides show in the viewport. The carousel does not move, and it does not show the arrows and the dots. |
|
|
133
|
+
|
|
134
|
+
A carousel can have fewer snaps than slides. For example, `slidesPerSnap: 2` puts two slides into each snap. Also, `containScroll: 'trimSnaps'` removes the snaps that show empty space at the ends. For this reason, the methods use two types of index:
|
|
135
|
+
|
|
136
|
+
- `goToSnap()`, `selectedSnap()` and `snapProgress()` use a snap index.
|
|
137
|
+
- `goToSlide()`, `selectedSlide()`, `slidesInView()` and `slideNodes()` use a slide index.
|
|
138
|
+
- `snapOfSlide(index)` gives the snap index of a slide.
|
|
139
|
+
|
|
140
|
+
## CSS layout
|
|
141
|
+
|
|
142
|
+
The library does not set the size of the slides or the space between them. It reads these values from the CSS and moves only the container.
|
|
143
|
+
|
|
144
|
+
| The CSS of the container | The result |
|
|
145
|
+
| --- | --- |
|
|
146
|
+
| `display: flex`, a row | A horizontal carousel |
|
|
147
|
+
| `flex-direction: column` | A vertical carousel |
|
|
148
|
+
| `display: grid` with `grid-auto-flow: column` | A horizontal carousel with more rows |
|
|
149
|
+
| `justify-content: center` | The selected slide is in the center |
|
|
150
|
+
| `justify-content: flex-end` | The selected slide is at the end |
|
|
151
|
+
| The margins of the slides and a negative margin of the container | The space between the slides. In a loop, also the space between the last slide and the first slide. |
|
|
152
|
+
| `direction: rtl` | A right-to-left carousel |
|
|
153
|
+
|
|
154
|
+
The carousel measures again when the CSS changes, when the page adds or removes a slide, and when an image loads. To add or remove a slide, change the elements in the container.
|
|
155
|
+
|
|
156
|
+
A carousel can start in a hidden element, such as a tab, an accordion or a modal window. It has no size, so it shows no arrows and no dots. When the element shows, the carousel measures and starts to move.
|
|
157
|
+
|
|
158
|
+
## Frameworks
|
|
159
|
+
|
|
160
|
+
1. Render the root and the viewport in the component.
|
|
161
|
+
2. When the component mounts, start the carousel on the viewport. The library finds the container in the viewport and adds no wrapper.
|
|
162
|
+
3. Before the component unmounts, destroy the carousel.
|
|
163
|
+
|
|
164
|
+
The library does not move the elements that the framework controls.
|
|
165
|
+
|
|
166
|
+
### React
|
|
167
|
+
|
|
168
|
+
In Strict Mode, React runs each effect two times in development. The cleanup function destroys the first carousel, and the second carousel replaces it.
|
|
169
|
+
|
|
170
|
+
```jsx
|
|
171
|
+
import { useEffect, useRef } from 'react'
|
|
172
|
+
import BetterCarousel from '@twistedandy/better-carousel'
|
|
173
|
+
import '@twistedandy/better-carousel/css'
|
|
174
|
+
|
|
175
|
+
export default function Carousel({ slides, options }) {
|
|
176
|
+
const viewport = useRef(null)
|
|
177
|
+
const carousel = useRef(null)
|
|
178
|
+
|
|
179
|
+
useEffect(() => {
|
|
180
|
+
carousel.current = BetterCarousel(viewport.current, options)
|
|
181
|
+
return () => carousel.current.destroy()
|
|
182
|
+
}, [])
|
|
183
|
+
|
|
184
|
+
return (
|
|
185
|
+
<>
|
|
186
|
+
<div className="better">
|
|
187
|
+
<div className="better_viewport" ref={viewport}>
|
|
188
|
+
<div className="items">
|
|
189
|
+
{slides.map((slide) => (
|
|
190
|
+
<div className="item" key={slide.id}>
|
|
191
|
+
<img src={slide.src} alt={slide.alt} />
|
|
192
|
+
</div>
|
|
193
|
+
))}
|
|
194
|
+
</div>
|
|
195
|
+
</div>
|
|
196
|
+
</div>
|
|
197
|
+
<button type="button" onClick={() => carousel.current.goToNext()}>Next slide</button>
|
|
198
|
+
</>
|
|
199
|
+
)
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Vue
|
|
204
|
+
|
|
205
|
+
```vue
|
|
206
|
+
<script setup>
|
|
207
|
+
import { onMounted, onBeforeUnmount, ref } from 'vue'
|
|
208
|
+
import BetterCarousel from '@twistedandy/better-carousel'
|
|
209
|
+
import '@twistedandy/better-carousel/css'
|
|
210
|
+
|
|
211
|
+
const props = defineProps({ slides: Array, options: Object })
|
|
212
|
+
const viewport = ref(null)
|
|
213
|
+
let carousel = null
|
|
214
|
+
|
|
215
|
+
onMounted(() => {
|
|
216
|
+
carousel = BetterCarousel(viewport.value, props.options)
|
|
217
|
+
})
|
|
218
|
+
|
|
219
|
+
onBeforeUnmount(() => carousel?.destroy())
|
|
220
|
+
</script>
|
|
221
|
+
|
|
222
|
+
<template>
|
|
223
|
+
<div class="better">
|
|
224
|
+
<div ref="viewport" class="better_viewport">
|
|
225
|
+
<div class="items">
|
|
226
|
+
<div v-for="slide in slides" :key="slide.id" class="item">
|
|
227
|
+
<img :src="slide.src" :alt="slide.alt" />
|
|
228
|
+
</div>
|
|
229
|
+
</div>
|
|
230
|
+
</div>
|
|
231
|
+
</div>
|
|
232
|
+
</template>
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### Svelte
|
|
236
|
+
|
|
237
|
+
This example is for Svelte 5. For Svelte 4, use `export let slides` and `export let options` in place of `$props()`.
|
|
238
|
+
|
|
239
|
+
```svelte
|
|
240
|
+
<script>
|
|
241
|
+
import { onMount } from 'svelte'
|
|
242
|
+
import BetterCarousel from '@twistedandy/better-carousel'
|
|
243
|
+
import '@twistedandy/better-carousel/css'
|
|
244
|
+
|
|
245
|
+
let { slides, options } = $props()
|
|
246
|
+
let viewport
|
|
247
|
+
|
|
248
|
+
onMount(() => {
|
|
249
|
+
const carousel = BetterCarousel(viewport, options)
|
|
250
|
+
return () => carousel.destroy()
|
|
251
|
+
})
|
|
252
|
+
</script>
|
|
253
|
+
|
|
254
|
+
<div class="better">
|
|
255
|
+
<div class="better_viewport" bind:this={viewport}>
|
|
256
|
+
<div class="items">
|
|
257
|
+
{#each slides as slide (slide.id)}
|
|
258
|
+
<div class="item"><img src={slide.src} alt={slide.alt} /></div>
|
|
259
|
+
{/each}
|
|
260
|
+
</div>
|
|
261
|
+
</div>
|
|
262
|
+
</div>
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### Solid
|
|
266
|
+
|
|
267
|
+
```jsx
|
|
268
|
+
import { onMount, onCleanup, For } from 'solid-js'
|
|
269
|
+
import BetterCarousel from '@twistedandy/better-carousel'
|
|
270
|
+
import '@twistedandy/better-carousel/css'
|
|
271
|
+
|
|
272
|
+
export default function Carousel(props) {
|
|
273
|
+
let viewport
|
|
274
|
+
|
|
275
|
+
onMount(() => {
|
|
276
|
+
const carousel = BetterCarousel(viewport, props.options)
|
|
277
|
+
onCleanup(() => carousel.destroy())
|
|
278
|
+
})
|
|
279
|
+
|
|
280
|
+
return (
|
|
281
|
+
<div class="better">
|
|
282
|
+
<div class="better_viewport" ref={viewport}>
|
|
283
|
+
<div class="items">
|
|
284
|
+
<For each={props.slides}>
|
|
285
|
+
{(slide) => <div class="item"><img src={slide.src} alt={slide.alt} /></div>}
|
|
286
|
+
</For>
|
|
287
|
+
</div>
|
|
288
|
+
</div>
|
|
289
|
+
</div>
|
|
290
|
+
)
|
|
291
|
+
}
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
### Rules for frameworks
|
|
295
|
+
|
|
296
|
+
- Do not render other elements after the viewport in the root. The library adds the arrows and the dots at the end of the root. To put them in a different element, set the [`arrows`](#options) and [`dots`](#options) options.
|
|
297
|
+
- To change the options, call `reinit(newOptions)`. The selected slide stays.
|
|
298
|
+
- With server-side rendering, start the carousel only in the browser: in `useEffect`, `onMounted` or `onMount`. The library needs the DOM.
|
|
299
|
+
|
|
300
|
+
NOTE: When the framework adds or removes a slide, the carousel measures again. A `reinit()` call is not necessary.
|
|
301
|
+
|
|
302
|
+
## Options
|
|
303
|
+
|
|
304
|
+
Set the options in one of these places:
|
|
305
|
+
|
|
306
|
+
- In the call: `BetterCarousel(element, options)`.
|
|
307
|
+
- In the `data-carousel` attribute, as JSON.
|
|
308
|
+
- In `BetterCarousel.defaults`, for all carousels.
|
|
309
|
+
|
|
310
|
+
If the call and the attribute set the same option, the value of the attribute applies.
|
|
311
|
+
|
|
312
|
+
```html
|
|
313
|
+
<div class="items carousel" data-carousel='{"loop":true,"autoplay":3000}'>...</div>
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
```js
|
|
317
|
+
// All carousels of the site
|
|
318
|
+
BetterCarousel.defaults = { dragThreshold: 2 }
|
|
319
|
+
|
|
320
|
+
// One carousel, with different options for a media query
|
|
321
|
+
BetterCarousel(element, {
|
|
322
|
+
align: 'center',
|
|
323
|
+
breakpoints: {
|
|
324
|
+
'(min-width: 1024px)': { drag: false },
|
|
325
|
+
},
|
|
326
|
+
})
|
|
327
|
+
|
|
328
|
+
// The options that need no example of their own
|
|
329
|
+
BetterCarousel(element, {
|
|
330
|
+
startSnap: 2, // Start at the third snap
|
|
331
|
+
duration: 600, // The duration of a motion by one snap, in ms
|
|
332
|
+
inViewThreshold: 0.5, // A slide is in view when half of it shows
|
|
333
|
+
resize: false, // Do not measure again when a size changes
|
|
334
|
+
slideChanges: false, // Do not watch for added and removed slides
|
|
335
|
+
wrapper: false, // Add no root and viewport: the page has them
|
|
336
|
+
})
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
<!-- generated:options -->
|
|
340
|
+
| Option | Type | Default | Description |
|
|
341
|
+
| --- | --- | --- | --- |
|
|
342
|
+
| `axis` | `'x'`, `'y'`, `'auto'` | `'auto'` | The axis of the motion. With `'auto'`, the CSS of the container sets the axis. ([example](https://twistedandy.github.io/better-carousel/#switch)) |
|
|
343
|
+
| `align` | `'start'`, `'center'`, `'end'`, `'auto'`, `function` | `'auto'` | The position of the selected snap in the viewport. A function gets `(viewSize, snapSize, index)` and returns the offset in px. With `'auto'`, `justify-content` sets the alignment. ([example](https://twistedandy.github.io/better-carousel/#center)) |
|
|
344
|
+
| `dir` | `'ltr'`, `'rtl'`, `'auto'` | `'auto'` | The text direction. With `'auto'`, the CSS `direction` sets it. ([example](https://twistedandy.github.io/better-carousel/#rtl)) |
|
|
345
|
+
| `loop` | `boolean` | `false` | The first slide comes after the last slide. ([example](https://twistedandy.github.io/better-carousel/#loop)) |
|
|
346
|
+
| `clones` | `'auto'`, `'fill'`, `false` | `'auto'` | `'auto'`: add clones only if the loop needs them. `'fill'`: add clones that fill the window. `false`: add no clones. ([example](https://twistedandy.github.io/better-carousel/#clones)) |
|
|
347
|
+
| `dragFree` | `boolean`, `'snap'` | `false` | `true`: glide after a drag and stop at any position. `'snap'`: glide and stop at the nearest snap. ([example](https://twistedandy.github.io/better-carousel/#free)) |
|
|
348
|
+
| `dragFriction` | `number` | `1` | The length of the glide after a fast drag: the glide distance is divided by this number. `2`: half the distance. `0.5`: 2 times the distance. It also changes how many snaps a flick moves. The value must be more than 0. ([example](https://twistedandy.github.io/better-carousel/#free)) |
|
|
349
|
+
| `containScroll` | `'trimSnaps'`, `'keepSnaps'`, `false` | `'trimSnaps'` | `'trimSnaps'`: no empty space at the ends. `'keepSnaps'`: no empty space, but keep a snap for each group. `false`: snaps can show empty space. ([example](https://twistedandy.github.io/better-carousel/#contain)) |
|
|
350
|
+
| `slidesPerSnap` | `number`, `'auto'` | `1` | The number of slides in one snap. `'auto'`: the slides that fit in the viewport. ([example](https://twistedandy.github.io/better-carousel/#groups)) |
|
|
351
|
+
| `skipSnaps` | `boolean`, `number` | `true` | A fast flick can move more than one snap. `false`: one snap. A number: the maximum number of snaps. ([example](https://twistedandy.github.io/better-carousel/#skip)) |
|
|
352
|
+
| `dragThreshold` | `number` | `10` | The distance in px that the pointer moves before a drag starts. |
|
|
353
|
+
| `duration` | `number` | `400` | The duration of a motion by one snap, in ms. A longer motion takes more time, to a maximum of 2 times this value. ([example](https://twistedandy.github.io/better-carousel/#options-usage)) |
|
|
354
|
+
| `startSnap` | `number` | `0` | The index of the snap at the start. ([example](https://twistedandy.github.io/better-carousel/#options-usage)) |
|
|
355
|
+
| `lazy` | `boolean`, `number` | `false` | `true`: start when the carousel comes within one screen of the view. A number: the distance in px. ([example](https://twistedandy.github.io/better-carousel/#lazy)) |
|
|
356
|
+
| `drag` | `boolean` | `true` | Drag with the mouse, the pen and the finger. |
|
|
357
|
+
| `wheel` | `boolean`, `'both'` | `true` | The mouse wheel moves a vertical carousel. `'both'`: also a horizontal carousel. `false`: the wheel does not move the carousel. ([example](https://twistedandy.github.io/better-carousel/#vertical)) |
|
|
358
|
+
| `keys` | `boolean` | `true` | The arrow keys move the carousel while the keyboard focus is in it: left and right in a horizontal carousel, up and down in a vertical carousel. A key in a form field does not move the carousel. |
|
|
359
|
+
| `resize` | `boolean` | `true` | Measure again when a size changes. ([example](https://twistedandy.github.io/better-carousel/#options-usage)) |
|
|
360
|
+
| `slideChanges` | `boolean` | `true` | Measure again when the page adds or removes a slide. ([example](https://twistedandy.github.io/better-carousel/#changes)) |
|
|
361
|
+
| `focus` | `boolean` | `true` | Go to a slide when it gets the keyboard focus. ([example](https://twistedandy.github.io/better-carousel/#controls)) |
|
|
362
|
+
| `inViewThreshold` | `number` | `0` | The part of a slide, from 0 to 1, that must show for `slidesInView()`. ([example](https://twistedandy.github.io/better-carousel/#options-usage)) |
|
|
363
|
+
| `active` | `boolean` | `true` | `false`: do not start the carousel. Use it in `breakpoints`. ([example](https://twistedandy.github.io/better-carousel/#breakpoints)) |
|
|
364
|
+
| `breakpoints` | `object` | `{}` | The options for media queries: `{ '(min-width: 768px)': { loop: true } }`. ([example](https://twistedandy.github.io/better-carousel/#breakpoints)) |
|
|
365
|
+
| `container` | `string` | `null` | The selector of the container, if the element is the root. |
|
|
366
|
+
| `slides` | `string` | `null` | The selector of the slides. With `null`, all children of the container are slides. |
|
|
367
|
+
| `wrapper` | `boolean` | `true` | Add the root and the viewport if the page does not have them. ([example](https://twistedandy.github.io/better-carousel/#options-usage)) |
|
|
368
|
+
| `arrows` | `boolean`, `Element`, `string` | `true` | Add the arrows to the root. `false`: no arrows. An element or a selector: add the arrows to that element. ([example](https://twistedandy.github.io/better-carousel/#heading)) |
|
|
369
|
+
| `dots` | `boolean`, `Element`, `string` | `true` | Add the dots. The values are the same as for `arrows`. ([example](https://twistedandy.github.io/better-carousel/#heading)) |
|
|
370
|
+
| `dotsStyle` | `'zoom'`, `'all'` | `'zoom'` | The style of the dots. `'zoom'`: a window of 5 dots that slides, with smaller dots at the ends. `'all'`: all dots with the same size. |
|
|
371
|
+
| `labels` | `object` | English | The texts for screen readers: `carousel`, `slide` (`'%d of %n'`), `prev`, `next`, `dot` (`'Go to slide %d'`), `play`, `pause`. `%d` is the slide number, and `%n` is the number of slides. ([example](#accessibility)) |
|
|
372
|
+
| `classes` | `string`, `object` | `null` | A class prefix such as `'embla'`, or an object with the names to change. The [Classes](#classes) table gives all names. ([example](https://twistedandy.github.io/better-carousel/#embla)) |
|
|
373
|
+
| `state` | `string` | `''` | The prefix of the state classes, such as `'is_'`. ([example](https://twistedandy.github.io/better-carousel/#embla)) |
|
|
374
|
+
| `sync` | carousel, `Element`, `string` | `null` | Another carousel, its container or a selector. This carousel follows the selected slide of the other carousel. A click on a slide selects it in the other carousel. ([example](https://twistedandy.github.io/better-carousel/#product)) |
|
|
375
|
+
| `autoplay` | `boolean`, `number`, `object` | `false` | Go to the next slide after a delay. `true`, a delay in ms, or an object. ([example](#autoplay)) |
|
|
376
|
+
| `autoScroll` | `boolean`, `number`, `object` | `false` | Move the slides at a constant speed. `true`, a speed in px/s, or an object. ([example](https://twistedandy.github.io/better-carousel/#logos)) |
|
|
377
|
+
| `autoHeight` | `boolean` | `false` | The viewport gets the height of the tallest slide in view. ([example](https://twistedandy.github.io/better-carousel/#height)) |
|
|
378
|
+
| `progress` | `boolean`, `function` | `false` | Follow the progress, from 0 to 1. `true` sets `--better-progress` on the root. A function gets `{ progress, snap }` on each frame of a motion. See [Progress and offset](#progress-and-offset). |
|
|
379
|
+
| `offset` | `boolean`, `function` | `false` | Follow the distance of each slide from its snap position, in slides. `true` sets `--better-offset` on each slide. A function gets `{ node, index, offset, distance, size, visible }` for each slide on each frame of a motion. |
|
|
380
|
+
<!-- /generated -->
|
|
381
|
+
|
|
382
|
+
### autoplay
|
|
383
|
+
|
|
384
|
+
The value is `true`, a delay in ms, or an object. In the object, `delay` can also be an array with one delay for each snap. A `data-delay` attribute on a slide sets the delay of that slide, and it has priority over `delay`.
|
|
385
|
+
|
|
386
|
+
The autoplay pauses in these conditions:
|
|
387
|
+
|
|
388
|
+
- The keyboard focus is in the carousel.
|
|
389
|
+
- The tab is hidden.
|
|
390
|
+
- The carousel is out of view.
|
|
391
|
+
|
|
392
|
+
If the user prefers reduced motion, the autoplay does not start. These are the default values:
|
|
393
|
+
|
|
394
|
+
```js
|
|
395
|
+
BetterCarousel(element, {
|
|
396
|
+
autoplay: {
|
|
397
|
+
delay: 4000, // ms on each slide, or an array with ms for each snap
|
|
398
|
+
stopOnInteraction: true, // A drag, an arrow or a dot stops the autoplay
|
|
399
|
+
pauseOnHover: false, // Pause while the mouse is on the carousel
|
|
400
|
+
pauseOnFocus: true, // Pause while the keyboard focus is in the carousel
|
|
401
|
+
stopOnLastSnap: false, // Stop at the last snap, if loop is false
|
|
402
|
+
playOnInit: true,
|
|
403
|
+
instant: false, // Jump to the next slide with no motion
|
|
404
|
+
timer: null, // A function that shows the time to the next slide
|
|
405
|
+
},
|
|
406
|
+
})
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
To show the time to the next slide, set `timer` to a function. The carousel calls it when the timer starts, with the delay in ms and the carousel. The function can return a cleanup function. The carousel calls the cleanup function when this timer ends or stops, for example at a pause. The library has no styles for a progress indicator.
|
|
410
|
+
|
|
411
|
+
```js
|
|
412
|
+
const bar = document.querySelector('.progress')
|
|
413
|
+
|
|
414
|
+
BetterCarousel(element, {
|
|
415
|
+
autoplay: {
|
|
416
|
+
timer: (delay) => {
|
|
417
|
+
const animation = bar.animate([{ scale: '0 1' }, { scale: '1 1' }], delay)
|
|
418
|
+
return () => animation.cancel()
|
|
419
|
+
},
|
|
420
|
+
},
|
|
421
|
+
})
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
An animation of `scale`, `translate` or `opacity` runs on the compositor: no script runs for each frame.
|
|
425
|
+
|
|
426
|
+
### autoScroll
|
|
427
|
+
|
|
428
|
+
The value is `true`, a speed in px/s, or an object. The motion is one animation on the compositor. The pause conditions are the same as for the autoplay. These are the default values:
|
|
429
|
+
|
|
430
|
+
```js
|
|
431
|
+
BetterCarousel(element, {
|
|
432
|
+
loop: true,
|
|
433
|
+
autoScroll: {
|
|
434
|
+
speed: 120, // px per second
|
|
435
|
+
direction: 'next', // or 'prev'
|
|
436
|
+
startDelay: 1000, // ms before the start, and after an interaction
|
|
437
|
+
stopOnInteraction: true,
|
|
438
|
+
pauseOnHover: false,
|
|
439
|
+
pauseOnFocus: true,
|
|
440
|
+
playOnInit: true,
|
|
441
|
+
},
|
|
442
|
+
})
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
### sync
|
|
446
|
+
|
|
447
|
+
The `sync` option links two carousels, for example a gallery and its thumbnails:
|
|
448
|
+
|
|
449
|
+
1. Put the same slides into the two carousels, in the same order.
|
|
450
|
+
2. Use buttons for the thumbnails, so that the keyboard can select them.
|
|
451
|
+
3. Set `sync` on the thumbnails carousel.
|
|
452
|
+
|
|
453
|
+
The thumbnails follow the main gallery, and a click on a thumbnail selects its photo. A drag moves only the thumbnails. The thumbnail of the selected photo gets the `selected` class. In this example, the `arrows` option puts the arrows of the main gallery next to the thumbnails.
|
|
454
|
+
|
|
455
|
+
```html
|
|
456
|
+
<div class="items carousel gallery_main" data-carousel='{"dots":false,"arrows":".gallery_nav"}'>...</div>
|
|
457
|
+
<div class="gallery_nav">
|
|
458
|
+
<div class="items carousel gallery_thumbs" data-carousel='{"sync":".gallery_main","arrows":false,"dots":false}'>
|
|
459
|
+
<button type="button" class="item"><img src="thumb-1.jpg" alt="Show photo 1" /></button>
|
|
460
|
+
...
|
|
461
|
+
</div>
|
|
462
|
+
</div>
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
The value of `sync` can be a selector, a container or a carousel. The library searches for a selector in the root of the carousel first, and then in each parent of the root. A carousel can follow only one other carousel.
|
|
466
|
+
|
|
467
|
+
### progress and offset
|
|
468
|
+
|
|
469
|
+
The `progress` and `offset` options give the position of the carousel on each frame of a motion. Use them for a progress bar, a parallax effect, or a fade. They are off by default, because a script runs on each frame while they are on.
|
|
470
|
+
|
|
471
|
+
With `true`, the carousel sets CSS variables:
|
|
472
|
+
|
|
473
|
+
- `--better-progress` on the root: the progress, from 0 to 1;
|
|
474
|
+
- `--better-offset` on each slide: the distance from the snap position of the slide, in slides. The value is 0 at the snap position, 1 for the next slide and -1 for the previous slide.
|
|
475
|
+
|
|
476
|
+
```html
|
|
477
|
+
<div class="items carousel" data-carousel='{"progress":true,"offset":true}'>...</div>
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
A progress bar at the bottom of the slides:
|
|
481
|
+
|
|
482
|
+
```css
|
|
483
|
+
.better_viewport::after {
|
|
484
|
+
content: "";
|
|
485
|
+
position: absolute;
|
|
486
|
+
inset: auto 0 0;
|
|
487
|
+
z-index: 3;
|
|
488
|
+
height: 4px;
|
|
489
|
+
background: currentColor;
|
|
490
|
+
transform-origin: left;
|
|
491
|
+
scale: var(--better-progress, 0) 1;
|
|
492
|
+
}
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
Parallax: each photo is larger than its slide, and it moves slower than the slide.
|
|
496
|
+
|
|
497
|
+
```css
|
|
498
|
+
.better .item {
|
|
499
|
+
overflow: hidden;
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
.better .item img {
|
|
503
|
+
scale: 1.3;
|
|
504
|
+
translate: calc(clamp(-1, var(--better-offset, 0), 1) * -10%) 0;
|
|
505
|
+
}
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
Scale and fade: the photos far from the selected snap are smaller and lighter.
|
|
509
|
+
|
|
510
|
+
```css
|
|
511
|
+
.better .item {
|
|
512
|
+
--distance: min(1, max(var(--better-offset, 0), -1 * var(--better-offset, 0)));
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
.better .item img {
|
|
516
|
+
scale: calc(1 - 0.25 * var(--distance));
|
|
517
|
+
opacity: calc(1 - 0.6 * var(--distance));
|
|
518
|
+
}
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
Change an element in the slide, not the slide. The carousel measures the slides, and a `scale` on a slide changes its size for the carousel.
|
|
522
|
+
|
|
523
|
+
A function gets a state object and the carousel. The carousel uses the same object for each call, so read the values during the call:
|
|
524
|
+
|
|
525
|
+
```js
|
|
526
|
+
BetterCarousel(element, {
|
|
527
|
+
// { progress, snap }: snap is the position between the snaps, for example 2.4
|
|
528
|
+
progress: ({ progress, snap }) => {
|
|
529
|
+
bar.style.scale = progress + ' 1';
|
|
530
|
+
},
|
|
531
|
+
// { node, index, offset, distance, size, visible }, one call for each slide
|
|
532
|
+
offset: ({ node, offset, visible }) => {
|
|
533
|
+
node.style.opacity = 0.4 + 0.6 * visible;
|
|
534
|
+
},
|
|
535
|
+
})
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
- `distance` is the same distance as `offset`, in px on the screen. A positive value is to the right or down.
|
|
539
|
+
- `size` is the size of the slide on the main axis, in px.
|
|
540
|
+
- `visible` is the part of the slide in the viewport, from 0 to 1.
|
|
541
|
+
- `index` is the index of the slide. A clone gives the index of its slide.
|
|
542
|
+
|
|
543
|
+
In loop mode, the progress goes from 1 back to 0. The auto scroll is a motion that does not stop: with these options, a script runs on each frame while it plays.
|
|
544
|
+
|
|
545
|
+
## Methods
|
|
546
|
+
|
|
547
|
+
`BetterCarousel(element, options)` returns the carousel. The methods below are the methods of the carousel, and of the `BetterCarousel` function.
|
|
548
|
+
|
|
549
|
+
<!-- generated:methods -->
|
|
550
|
+
| Method | Returns | Description |
|
|
551
|
+
| --- | --- | --- |
|
|
552
|
+
| `BetterCarousel(element, options)` | carousel | Start a carousel on a container or on its viewport. If the element has a carousel, return that carousel. |
|
|
553
|
+
| `goToSnap(index, instant)` | - | Go to a snap. `index` is a snap index. With `instant` set to `true`, jump with no motion. |
|
|
554
|
+
| `goToNext(instant)`, `goToPrev(instant)` | - | Go to the next or the previous snap. |
|
|
555
|
+
| `goToSlide(index, instant)` | - | Go to the snap that shows a slide. `index` is a slide index. This slide becomes the selected slide. |
|
|
556
|
+
| `canGoToNext()`, `canGoToPrev()` | `boolean` | `true` if a next or a previous snap exists. In a loop, `true` if not all slides fit. |
|
|
557
|
+
| `selectedSnap()`, `previousSnap()` | `number` | The index of the selected snap, or of the snap before it. |
|
|
558
|
+
| `selectedSlide()` | `number` | The index of the selected slide. With `sync`, the slide that is selected in the other carousel. |
|
|
559
|
+
| `snapOfSlide(index)` | `number` | The index of the snap that shows a slide. |
|
|
560
|
+
| `snapProgress()` | `number[]` | The progress of each snap, from 0 to 1. |
|
|
561
|
+
| `progress()` | `number` | The progress now, from 0 to 1, also during a motion. |
|
|
562
|
+
| `slidesInView()` | `number[]` | The indexes of the slides in view. |
|
|
563
|
+
| `slideNodes()` | `HTMLElement[]` | The slides. The list does not include the clones. |
|
|
564
|
+
| `rootNode()`, `viewportNode()`, `containerNode()` | `HTMLElement` | The root, the viewport and the container. |
|
|
565
|
+
| `isFit()` | `boolean` | `true` if all slides fit in the viewport. |
|
|
566
|
+
| `options()` | `object` | The options that apply now, after the breakpoints. |
|
|
567
|
+
| `reinit(options)` | - | Merge new options and start again. The selected slide stays. |
|
|
568
|
+
| `destroy()` | - | Stop the carousel and restore the markup. |
|
|
569
|
+
| `on(name, handler)`, `off(name, handler)` | carousel | Add or remove an event handler. The handler gets `(carousel, name)`. |
|
|
570
|
+
| `autoplay` | `object` | Only with the `autoplay` option: `play()`, `stop()`, `reset()` and `isPlaying()`. |
|
|
571
|
+
| `autoScroll` | `object` | Only with the `autoScroll` option: `play()`, `stop()` and `isPlaying()`. |
|
|
572
|
+
| `BetterCarousel.get(element)` | carousel, `undefined` | The carousel of a root, a viewport or a container. |
|
|
573
|
+
| `BetterCarousel.initAll(selector, options)` | carousel[] | Start a carousel on each element that matches the selector. |
|
|
574
|
+
| `BetterCarousel.defaults` | `object` | The options for all carousels. Set it before you start the carousels. |
|
|
575
|
+
<!-- /generated -->
|
|
576
|
+
|
|
577
|
+
```js
|
|
578
|
+
const carousel = BetterCarousel(element, { loop: true })
|
|
579
|
+
|
|
580
|
+
carousel.on('select', (carousel) => {
|
|
581
|
+
console.log('Slide', carousel.selectedSlide())
|
|
582
|
+
})
|
|
583
|
+
|
|
584
|
+
document.querySelector('.next').addEventListener('click', () => carousel.goToNext())
|
|
585
|
+
```
|
|
586
|
+
|
|
587
|
+
## Events
|
|
588
|
+
|
|
589
|
+
Add a handler with `on(name, handler)`, and remove it with `off(name, handler)`. The handler gets `(carousel, name)`.
|
|
590
|
+
|
|
591
|
+
<!-- generated:events -->
|
|
592
|
+
| Event | When |
|
|
593
|
+
| --- | --- |
|
|
594
|
+
| `init` | The carousel measured the layout for the first time. |
|
|
595
|
+
| `reinit` | A `reinit()` call or a breakpoint started the carousel again. |
|
|
596
|
+
| `resize` | The layout changed. |
|
|
597
|
+
| `select` | The selected snap changed. |
|
|
598
|
+
| `scroll` | The position changed during a motion or a drag. |
|
|
599
|
+
| `settle` | A motion stopped. |
|
|
600
|
+
| `dragstart`, `dragend` | A drag started or stopped. |
|
|
601
|
+
| `slidesinview` | The slides in view changed. |
|
|
602
|
+
| `slideschanged` | The page added or removed a slide. |
|
|
603
|
+
| `slidefocus` | A slide got the keyboard focus. |
|
|
604
|
+
| `autoplay:play`, `autoplay:stop` | The autoplay started or stopped. |
|
|
605
|
+
| `autoscroll:play`, `autoscroll:stop` | The auto scroll started or stopped. |
|
|
606
|
+
| `destroy` | The carousel stopped and restored the markup. |
|
|
607
|
+
<!-- /generated -->
|
|
608
|
+
|
|
609
|
+
CAUTION: Add a `scroll` handler only if you need it. With this handler, each motion runs in a `requestAnimationFrame` loop on the main thread.
|
|
610
|
+
|
|
611
|
+
## Styling
|
|
612
|
+
|
|
613
|
+
The stylesheet has the rules that the carousel needs. It also has the look of the arrows, the dots and the play button.
|
|
614
|
+
|
|
615
|
+
- To change the colors, set the CSS variables.
|
|
616
|
+
- To change the class names, compile the SCSS file.
|
|
617
|
+
|
|
618
|
+
### CSS variables
|
|
619
|
+
|
|
620
|
+
The buttons and the dots use the button variables of the theme. The arrow icon is an inline SVG in the stylesheet. To use a different icon, set `--button-arrow`.
|
|
621
|
+
|
|
622
|
+
```css
|
|
623
|
+
:root {
|
|
624
|
+
--height-button: 2.5rem; /* The size of the buttons */
|
|
625
|
+
--button-arrow: url(arrow.svg); /* Optional: the default is a chevron */
|
|
626
|
+
--button-border: #7c3aed;
|
|
627
|
+
--button-base: #7c3aed; /* Also the selected dot */
|
|
628
|
+
--button-text: #fff;
|
|
629
|
+
--button-border-active: #6d28d9;
|
|
630
|
+
--button-base-active: #6d28d9;
|
|
631
|
+
--button-text-active: #fff;
|
|
632
|
+
--button-border-disabled: #e8e8e8;
|
|
633
|
+
--button-base-disabled: #f5f5f5;
|
|
634
|
+
--button-text-disabled: #74787d; /* Also the dots */
|
|
635
|
+
}
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
### SCSS
|
|
639
|
+
|
|
640
|
+
The SCSS file uses `@import` and global variables, so it compiles with Dart Sass and with node-sass. Set the variables before the import:
|
|
641
|
+
|
|
642
|
+
```scss
|
|
643
|
+
$better: 'embla'; // The class prefix: .embla, .embla_viewport, .embla_button
|
|
644
|
+
$better-state: 'is_'; // The prefix of the state classes: .is_selected, .is_current
|
|
645
|
+
$better-look: false; // Only the rules that the carousel needs
|
|
646
|
+
$better-arrow: url(arrow.svg); // The default icon of the arrows. The --button-arrow variable comes first.
|
|
647
|
+
|
|
648
|
+
@import 'better-carousel';
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
Then set the same names in the options: `{ classes: 'embla', state: 'is_' }`.
|
|
652
|
+
|
|
653
|
+
### Classes
|
|
654
|
+
|
|
655
|
+
These are the default class names. A prefix in `classes` changes the first part of the names. The `state` prefix changes the state classes: `selected`, `dragging`, `playing` and the classes of the dots.
|
|
656
|
+
|
|
657
|
+
<!-- generated:classes -->
|
|
658
|
+
| Class | Element |
|
|
659
|
+
| --- | --- |
|
|
660
|
+
| `better` | The root |
|
|
661
|
+
| `better_viewport` | The viewport |
|
|
662
|
+
| `better_container` | The container |
|
|
663
|
+
| `better_horizontal`, `better_vertical` | The axis, on the root |
|
|
664
|
+
| `better_fit` | On the root, if all slides fit |
|
|
665
|
+
| `better_auto_height` | On the root, with `autoHeight` |
|
|
666
|
+
| `better_button`, `better_prev`, `better_next`, `better_play` | The buttons |
|
|
667
|
+
| `better_dots`, `better_dots_track`, `better_dot` | The window of the dots, the row that slides in it, and the dots |
|
|
668
|
+
| `better_dots_marker` | The marker of the selected dot |
|
|
669
|
+
| `better_dots_all` | On the window of the dots, with `dotsStyle: 'all'` |
|
|
670
|
+
| `selected` | The selected slide |
|
|
671
|
+
| `clone` | A clone of a slide |
|
|
672
|
+
| `dragging` | On the root, during a drag |
|
|
673
|
+
| `playing` | On the root, while the autoplay or the auto scroll plays |
|
|
674
|
+
| `current`, `prev`, `next`, `first`, `last` | The selected dot and the four dots around it |
|
|
675
|
+
<!-- /generated -->
|
|
676
|
+
|
|
677
|
+
```js
|
|
678
|
+
// .embla, .embla_viewport, .embla_button, .is_selected
|
|
679
|
+
BetterCarousel(element, { classes: 'embla', state: 'is_' })
|
|
680
|
+
|
|
681
|
+
// Change one name
|
|
682
|
+
BetterCarousel(element, { classes: { selected: 'snapped' } })
|
|
683
|
+
```
|
|
684
|
+
|
|
685
|
+
## Accessibility
|
|
686
|
+
|
|
687
|
+
The carousel follows the carousel pattern of the WAI-ARIA Authoring Practices and WCAG 2.1 AA.
|
|
688
|
+
|
|
689
|
+
- The root is a region with the name "Carousel". Each slide has a name such as "2 of 8". A slide that is an `article` or a list item keeps its own role.
|
|
690
|
+
- The arrows and the dots are buttons with names. A screen reader reads each new slide (`aria-live`), but not during the autoplay.
|
|
691
|
+
- Tab moves the focus through the links and the fields in the slides. The carousel moves to show the focused element.
|
|
692
|
+
- While the focus is in the carousel, the arrow keys go to the previous and the next slide. To turn them off, set `keys: false`.
|
|
693
|
+
- Clones are `inert` and hidden from screen readers.
|
|
694
|
+
- The autoplay and the auto scroll have a play and pause button (WCAG 2.2.2). The keyboard focus pauses them. If the user prefers reduced motion, they do not start.
|
|
695
|
+
- A drag across the axis scrolls the page. A link opens on a click, but not after a drag.
|
|
696
|
+
|
|
697
|
+
To translate the labels, set `labels`. In the texts, `%d` is the slide number, and `%n` is the number of slides:
|
|
698
|
+
|
|
699
|
+
```js
|
|
700
|
+
BetterCarousel.defaults = {
|
|
701
|
+
labels: {
|
|
702
|
+
carousel: 'Karussell',
|
|
703
|
+
slide: '%d von %n',
|
|
704
|
+
prev: 'Vorheriges Bild',
|
|
705
|
+
next: 'Nächstes Bild',
|
|
706
|
+
dot: 'Zu Bild %d',
|
|
707
|
+
play: 'Diashow starten',
|
|
708
|
+
pause: 'Diashow anhalten',
|
|
709
|
+
},
|
|
710
|
+
}
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
## Performance
|
|
714
|
+
|
|
715
|
+
The library is made for slow phones. A motion runs on the compositor, and a carousel at rest uses no CPU.
|
|
716
|
+
|
|
717
|
+
<!-- generated:sizes -->
|
|
718
|
+
| File | Minified | Gzip | Brotli |
|
|
719
|
+
| --- | --- | --- | --- |
|
|
720
|
+
| `better-carousel.min.js` | 28.9 KB | 11.6 KB | 10.6 KB |
|
|
721
|
+
| `better-carousel.css` | 4.7 KB | 1.3 KB | 1.1 KB |
|
|
722
|
+
| Total | 33.6 KB | 12.9 KB | 11.7 KB |
|
|
723
|
+
<!-- /generated -->
|
|
724
|
+
|
|
725
|
+
The [Comparison](#comparison) section gives the sizes and the runtime costs of other carousel libraries.
|
|
726
|
+
|
|
727
|
+
| Measure, on a phone with a CPU 4 times slower | Better Carousel |
|
|
728
|
+
| --- | --- |
|
|
729
|
+
| CPU load during 10 s of auto scroll | 0.5% |
|
|
730
|
+
| CPU load during 10 s of autoplay | 1.1% |
|
|
731
|
+
| Total Blocking Time added at page load | 0 ms |
|
|
732
|
+
| Layout shift | 0 |
|
|
733
|
+
|
|
734
|
+
- A motion is a Web Animations API animation of `translate`. No script runs on each frame.
|
|
735
|
+
- The auto scroll is one animation that does not stop. During the motion, the browser does no script, style, layout or paint work.
|
|
736
|
+
- One `ResizeObserver` serves all carousels. It reads the layout of all carousels first, and then it writes. For this reason, the browser calculates the layout only one time.
|
|
737
|
+
- Only two elements of the dots animate: the row of the dots and the marker of the selected dot. Both move with `translate`. A click on a dot causes no layout work.
|
|
738
|
+
- The listeners for the autoplay and the mouse wheel exist only while they can do something.
|
|
739
|
+
- The `progress` and `offset` options run a script on each frame of a motion. For this reason, they are off by default.
|
|
740
|
+
|
|
741
|
+
## Comparison
|
|
742
|
+
|
|
743
|
+
This benchmark compares Better Carousel with Swiper, Embla Carousel and Glide in Chrome. All libraries make the same carousel: 10 slides, the loop, the drag, the arrows, the dots and a motion of 400 ms. Embla uses the arrows, the dots and the CSS of its own examples, and the plugins for the same features. [bench/README.md](bench/README.md) gives the method, the metrics, the profiles and the steps to run the benchmark on your computer.
|
|
744
|
+
|
|
745
|
+
On a phone with a CPU 4 times slower:
|
|
746
|
+
|
|
747
|
+
- With all features, Better Carousel is 13.3 KB gzip. Embla is 13.5 KB and Swiper 32.9 KB with the same features. Embla still has no names for screen readers and no arrow keys. Glide does not have all of these features.
|
|
748
|
+
- 6 slide changes take 180 ms of main-thread time. Swiper takes 221 ms, Glide 329 ms and Embla 1584 ms.
|
|
749
|
+
- The autoplay uses 0.9% of the CPU. Glide uses 2.4%, Swiper 24.4% and Embla 32.2%.
|
|
750
|
+
- 5 drags take 1053 ms, about the same as Swiper (1024 ms). Glide takes 1732 ms and Embla 3587 ms. A drag causes the fewest paints of all libraries, and no layout shift.
|
|
751
|
+
- A page with 10 carousels has 28 ms of Total Blocking Time. Swiper has 61 ms and Glide 42 ms. Embla has 18 ms.
|
|
752
|
+
|
|
753
|
+
Measured with Chrome 157.0.8103.51 (headless) on 12th Gen Intel(R) Core(TM) i9-12900HK, 20 threads, 64 GB of memory, 2026-11-17. Each value is the median of 3 rounds.
|
|
754
|
+
|
|
755
|
+
### Bundle size
|
|
756
|
+
|
|
757
|
+

|
|
758
|
+
|
|
759
|
+
| Library | Core | Typical | Typical, brotli | All features | Shipped files |
|
|
760
|
+
| --- | ---: | ---: | ---: | ---: | ---: |
|
|
761
|
+
| **Better Carousel 1.0.0** | 13.3 | **13.3** | 12.1 | 13.3 | 12.9 |
|
|
762
|
+
| Swiper 14.4.0 | 21.7 | **29.7** | 26.2 | 32.9 | 46.2 |
|
|
763
|
+
| Embla Carousel 8.6.0 | 7.6 | **9.7** | 8.7 | 13.5 | 7.0 |
|
|
764
|
+
| Glide 3.7.1 | 6.9 | **8.3** | 7.4 | not available | 8.7 |
|
|
765
|
+
|
|
766
|
+
KB after gzip, JS and CSS. Core: the smallest setup that the user can drag. Typical: the setup of the tests below, with the loop, the arrows, the dots, the autoplay and the accessibility module. All features: the typical setup, the mouse wheel, the auto scroll, the auto height, the free drag and the sync. Shipped files: the minified JS and CSS files of the package, as they are.
|
|
767
|
+
|
|
768
|
+
### Mobile, CPU 4 times slower
|
|
769
|
+
|
|
770
|
+

|
|
771
|
+
|
|
772
|
+

|
|
773
|
+
|
|
774
|
+

|
|
775
|
+
|
|
776
|
+

|
|
777
|
+
|
|
778
|
+
| Library | Load, ms | Blocking, ms | Layout shift | Idle CPU, % | Navigate, ms | Navigate paints | Autoplay CPU, % | Drag, ms | Drag paints | Busy: bad frames, % |
|
|
779
|
+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
780
|
+
| **Better Carousel** | 198 | 28 | 0.000 | 0.2 | 180 | 12 | 0.9 | 1053 | 8 | 3.2 |
|
|
781
|
+
| Swiper | 239 | 61 | 0.000 | 0.1 | 221 | 12 | 24.4 | 1024 | 10 | 4.3 |
|
|
782
|
+
| Embla Carousel | 190 | 18 | 0.000 | 0.2 | 1584 | 12 | 32.2 | 3587 | 10 | 26.2 |
|
|
783
|
+
| Glide | 221 | 42 | 0.000 | 0.1 | 329 | 22 | 2.4 | 1732 | 20 | 1.3 |
|
|
784
|
+
| No carousel | 117 | 0 | 0.000 | 0.2 | 14 | 0 | 0.1 | 354 | 0 | - |
|
|
785
|
+
|
|
786
|
+
### Desktop
|
|
787
|
+
|
|
788
|
+
| Library | Load, ms | Blocking, ms | Layout shift | Idle CPU, % | Navigate, ms | Navigate paints | Autoplay CPU, % | Drag, ms | Drag paints | Busy: bad frames, % |
|
|
789
|
+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
|
|
790
|
+
| **Better Carousel** | 40 | 0 | 0.000 | 0.0 | 37 | 12 | 0.4 | 174 | 30 | 1.5 |
|
|
791
|
+
| Swiper | 51 | 0 | 0.000 | 0.0 | 29 | 12 | 3.3 | 146 | 16 | 1.2 |
|
|
792
|
+
| Embla Carousel | 42 | 0 | 0.000 | 0.0 | 266 | 12 | 5.6 | 518 | 60 | 15.7 |
|
|
793
|
+
| Glide | 47 | 0 | 0.000 | 0.0 | 49 | 26 | 0.6 | 303 | 22 | 0.7 |
|
|
794
|
+
| No carousel | 30 | 0 | 0.000 | 0.1 | 3 | 0 | 0.0 | 45 | 0 | - |
|
|
795
|
+
|
|
796
|
+
Load: the main-thread time and the Total Blocking Time of a page with 10 carousels. Navigate: 6 calls of `next()`. Drag: 5 drags. Busy: the share of frames that were dropped or late during navigate, while another script blocks the main thread. Less is better in all columns.
|
|
797
|
+
|
|
798
|
+
### Features
|
|
799
|
+
|
|
800
|
+
| Feature | Better | Swiper | Embla | Glide |
|
|
801
|
+
| --- | ---: | ---: | ---: | ---: |
|
|
802
|
+
| Slide sizes and gaps from CSS | yes | partly (`slidesPerView: 'auto'`) | yes | no |
|
|
803
|
+
| Loop without clones | yes | yes | yes | no |
|
|
804
|
+
| Vertical | yes | yes | yes | no |
|
|
805
|
+
| Right-to-left | yes | yes | yes | yes |
|
|
806
|
+
| Breakpoints | yes | yes | yes | yes |
|
|
807
|
+
| Free drag with momentum | yes | module | yes | no |
|
|
808
|
+
| Arrows and dots | yes | modules | no | your markup |
|
|
809
|
+
| Autoplay | yes | module | plugin | yes |
|
|
810
|
+
| Auto scroll without stops | yes | partly (autoplay with delay 0) | plugin | no |
|
|
811
|
+
| Auto height | yes | yes | plugin | no |
|
|
812
|
+
| Sync of two carousels | yes | module | no | no |
|
|
813
|
+
| Mouse wheel | yes | module | plugin of a third party | no |
|
|
814
|
+
| Arrow keys | yes | module | no | yes |
|
|
815
|
+
| Names for screen readers | yes | module | no | no |
|
|
816
|
+
| Start only when near the screen | yes | no | no | no |
|
|
817
|
+
| Fade and other effects | no | modules (fade, cube, flip, coverflow, cards, creative) | plugin (fade) | no |
|
|
818
|
+
| TypeScript types | yes | yes | yes | separate package |
|
|
819
|
+
|
|
820
|
+
Run the benchmark: `npm run bench`. The [bench/README.md](bench/README.md) file gives the method and the options.
|
|
821
|
+
|
|
822
|
+
## Development
|
|
823
|
+
|
|
824
|
+
```sh
|
|
825
|
+
npm install
|
|
826
|
+
npm run dev # build again after each change
|
|
827
|
+
npm run build # build dist/ and demo/demo.css, then update the docs
|
|
828
|
+
npm run docs # update the generated parts of README.md and index.html
|
|
829
|
+
npm test # unit tests
|
|
830
|
+
npm run e2e # browser tests in Chrome
|
|
831
|
+
```
|
|
832
|
+
|
|
833
|
+
The browser tests open `http://better.test/` in Chrome. To use a different address or a different Chrome, set `URL` and `CHROME`.
|
|
834
|
+
|
|
835
|
+
The docs page is [`index.html`](index.html). Its scripts and styles are in [`demo/`](demo). The reference tables and the file sizes in README.md and index.html, and the `Options` interface in [`src/types/better-carousel.d.ts`](src/types/better-carousel.d.ts), come from [`scripts/reference.js`](scripts/reference.js). Do not edit the parts in the `generated` HTML comments. Edit `scripts/reference.js`, and then run `npm run docs`.
|
|
836
|
+
|
|
837
|
+
## License
|
|
838
|
+
|
|
839
|
+
[MIT](LICENSE)
|