1.1.0 • Published 1 year ago

@warren-bank/svelte-glider v1.1.0

Weekly downloads
-
License
GPL-2.0
Repository
github
Last release
1 year ago

svelte-glider

A Svelte wrapper for Glider.js.

Demo

Quick Start

Installation:

npm install "@warren-bank/svelte-glider"

Usage

<script lang="ts">
  import Glider from '@warren-bank/svelte-glider'

  import 'glider-js/glider.min.css'
  import '@warren-bank/svelte-glider/glider.defaults.css'
</script>

<Glider
  class="gradient-outline hide-scrollbar"
  draggable
  hasArrows
  hasDots
  slidesToShow={2}
  slidesToScroll={1}
>
  <div class="slide"><h1>1</h1></div>
  <div class="slide"><h1>2</h1></div>
  <div class="slide"><h1>3</h1></div>
  <div class="slide"><h1>4</h1></div>
  <div class="slide"><h1>5</h1></div>
  <div class="slide"><h1>6</h1></div>
  <div class="slide"><h1>7</h1></div>
  <div class="slide"><h1>8</h1></div>
  <div class="slide"><h1>9</h1></div>
  <div class="slide"><h1>10</h1></div>
  <div class="slide"><h1>11</h1></div>
  <div class="slide"><h1>12</h1></div>
</Glider>

CSS

You may import the Glider.js CSS:

import 'glider-js/glider.min.css'

Note that the glider-js module is a dependency of _this package. As such, your project can import its CSS file without needing to add glider-js as an explicit dependency._

Note that this CSS only includes the minimal set of rules required for basic functionality. You will want to include additional style for proper appearance.

Additionally, this package exposes a CSS file containing minimal appearance styling intended to provide sane defaults. The above usage example is styled by this CSS file:

import '@warren-bank/svelte-glider/glider.defaults.css'

Though CSS bundling is recommended, if necessary, both of these CSS files could be included into an HTML document by external links:

<link
  rel="stylesheet"
  href="https://unpkg.com/glider-js@1.7.9/glider.min.css"
/>

<link
  rel="stylesheet"
  href="https://unpkg.com/@warren-bank/svelte-glider@1.0.1/defaults/glider.defaults.css"
/>

Glider Svelte component parameters

ParameterDescription
idAdd "id" attribute with specified value to DOM element used to initialize Glider.js
hasArrowsShow/hide arrows. (default = false)
hasDotsShow/hide dots. (default = false)
scrollToSlideStarting slide (default = 0)
scrollToPageStarting page (default = 0)
slidesToShowThe number of slides to show in container. If this value is set to auto, it will be automatically calculated based upon the number of items able to fit within the container viewport. This requires setting the itemWidth option.
slidesToScrollThe number of slides to scroll when arrow navigation is used. If this value is set to auto, it will match the value of slidesToScroll.
itemWidthThis value is ignored unless slidesToShow is set to auto, in which it is then required.
exactWidthThis prevents resizing items to fit when slidesToShow is set to auto.
resizeLockIf true, Glider.js will lock to the nearest slide on resizing of the window
rewindIf true, Glider.js will scroll to the beginning/end when its respective endpoint is reached
durationAn aggravator used to control animation speed. Higher is slower. (default = 0.5)
dotsA string containing the dot container selector
arrowsAn object containing the prev/next arrows selectors
draggableIf true, the list can be scrolled by click and dragging with the mouse. (default = false)
dragVelocityHow much to aggravate the velocity of the mouse dragging. (default = 3.3)
scrollPropagateWhether or not to release the scroll events from the container. (default = true)
scrollLockIf true, Glider.js will scroll to the nearest slide after any scroll interactions. (default = false)
skipTrackWhether or not Glider.js should skip wrapping its children with a 'glider-track' <div>. NOTE: If true, Glider.js will assume that the 'glider-track' element has been added manually. All slides must be children of the track element. (default = false)
scrollLockDelayHow long (ms) to wait after scroll event before locking, if too low, it might interrupt normal scrolling. (default = 250)
responsiveAn object containing custom settings per provided breakpoint. Glider.js breakpoints are mobile-first, be conscious of your ordering. Supported responsive settings are slidesToShow, slidesToScroll, itemWidth, and duration.
containerComponentReplace container <div> with a Svelte component.
containerElementReplace container <div> with a different HTML element.
easingUse any custom easing function, compatible with most easing plugins.

Glider Svelte component slots

SlotDescription
iconLeftLeft arrow. (default = '«'). Ignored when either: hasArrows is false, or arrows.prev parameter is defined.
iconRightRight arrow. (default = '»') Ignored when either: hasArrows is false, or arrows.next parameter is defined.

Example: Arrows (parameter, CSS selectors)

<Glider
  hasArrows
  arrows={{
    prev: '#buttonPrev',
    next: '#buttonNext'
  }}
>
  <!-- ... -->
</Glider>

Note that if you have multiple Glider elements on the same page, you need to assign a different CSS selector to each Glider.

Example: Arrows (parameter, DOM elements)

<Glider
  hasArrows
  arrows={{
    prev: document.getElementById("prev"),
    next: document.getElementById("next")
  }}
>
  <!-- ... -->
</Glider>

Example: Arrows (slots)

<Glider
  hasArrows
>
  <button slot="iconLeft">Prev</button>
  <button slot="iconRight">Next</button>
  <!-- ... -->
</Glider>

Responsive mode

You can set different settings for different viewport widths.

<Glider
  slidesToShow={1}
  scrollLock
  responsive={[
    {
      breakpoint: 864,
      settings: {
        slidesToShow: 3,
      },
    },
  ]}
>
  <!-- ... -->
</Glider>

Note that Glider.js is designed to be mobile-first, so the order of your breakpoints should be small-to-large.

Example: Replace container (HTML element)

<Glider
  containerElement="p"
>
  <!-- ... -->
</Glider>

Example: Replace container (Svelte component)

<script lang="ts">
  import {P} from 'flowbite-svelte'
</script>

<Glider
  containerComponent={P}
>
  <!-- ... -->
</Glider>

Events

EventDescription
onLoadCalled after Glider component is initialized.
onAnimatedCalled whenever a Glider.js paging animation is complete
onRemoveCalled whenever a Glider.js animation is complete
onSlideVisibleCalled whenever a slide a shown. Passed an object containing the slide index
onRefreshCalled whenever Glider.js refreshes it's elements or settings
onAddCalled whenever an item is added to Glider.js
onDestroyCalled whenever a Glider.js is destroyed
onSlideHiddenCalled whenever a slide a hidden. Passed an object containing the slide index

Glider.js Instance Methods

To get access to the instance of Glider.js used by a Glider Svelte component:

  1. bind the Glider Svelte component to a local variable
  2. wait until after the onMount component lifecycle event is called
  3. get a reference to the instance of Glider.js from the component method: getGliderJs()
<script lang="ts">
  import {onMount} from 'svelte'

  let gliderRef
  let gliderJs

  onMount(() => {
    gliderJs = gliderRef.getGliderJs()
  })
</script>

<Glider
  bind:this={gliderRef}
>
  <!-- ... -->
</Glider>

Perspective View

The CSS for the "Perspective View" Demo is not included in Glider.js or this package. You can find it in perspective.css. Please do not file bugs for it as I do not want to support it.

Examples

You may view the examples used in the docs page in the ./examples directory.

FAQs

Can I customize the appearance of the dots/pagination elements?

You may customize the dots by overriding the CSS for div.glider-dots and button.glider-dot.

Alternatively, you may pass a CSS selector to the dots property to assign a DOM element as the container for the Glider's pagination. This allows you to override the CSS for .glider-dots using CSS specificity.

.my-dots-container.glider-dots {
  /* ... */
}

This is also possible when using CSS modules and allows you to have multiple Glider components on the same page, each with different styles.

<div class={styles.banner}>
  <Glider
    dots={`.${style.dots}`}
    slidesToShow={1}
  >
    <!-- ... -->
  </Glider>
  <div class={style.dots} />
</div>

Can I lazyload images on inactive slides?

The recommended approach for lazy loading images is to use the browser's loading="lazy" implementation. You can use the slide's index to know which images should have the attribute set.

Which browsers are supported?

As svelte-glider is a wrapper for Glider.js, it should run on all modern browsers. Support for older browsers can be achieved by polyfilling document.classList, window.requestAnimationFrame, Object.assign and CustomEvent.

Building

npm install

cd docs
npm install
npm run build

# serve ./build

Legal

Thanks to

  • Nick Piscitelli
  • Kevin Farrugia
    • for his react-glider ReactJS wrapper for Glider.js
    • although our two projects don't share any code, the excellent organization of his project allowed me to use his docs and examples as a starting point that significantly sped up my work. In fact, version 1.0 was published in less than one day.
1.1.0

1 year ago

1.0.0

1 year ago