GlideJS - Documentation

Getting Started

Installation

Glide.js can be installed in several ways:

1. Using npm or yarn:

This is recommended for managing dependencies in larger projects.

npm install glidejs

or

yarn add glidejs

2. Downloading the files directly:

You can download the minified JavaScript file (glide.min.js) and CSS file (glide.core.min.css) from the Glide.js releases page. Include these files in your project’s HTML <head> or <body>, making sure to place the CSS file before the JavaScript file:

<link rel="stylesheet" href="glide.core.min.css">
<script src="glide.min.js"></script>

3. Using a CDN:

For quick prototyping or small projects, you can use a CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@glidejs/glide@3/dist/css/glide.core.min.css">
<script src="https://cdn.jsdelivr.net/npm/@glidejs/glide@3/dist/js/glide.min.js"></script>

(Remember to replace with the appropriate version if needed).

Basic Usage

After installation, you need to create the HTML structure for your slider and then initialize Glide.js. The basic HTML structure requires a track element containing slides:

<div class="glide">
  <div class="glide__track" data-glide-el="track">
    <ul class="glide__slides">
      <li class="glide__slide">
        <img src="image1.jpg" alt="Image 1">
      </li>
      <li class="glide__slide">
        <img src="image2.jpg" alt="Image 2">
      </li>
      <li class="glide__slide">
        <img src="image3.jpg" alt="Image 3">
      </li>
    </ul>
  </div>
  <div class="glide__arrows" data-glide-el="controls[nav]">
    <button class="glide__arrow glide__arrow--prev" data-glide-dir="<">prev</button>
    <button class="glide__arrow glide__arrow--next" data-glide-dir=">">next</button>
  </div>
</div>

Then, initialize Glide with a single line of JavaScript:

new Glide('.glide').mount();

This will create a basic slider with navigation arrows. More advanced options are available through configuration, described in other sections of this manual.

First Example

Let’s combine the installation and basic usage steps to create a working example.

First, include the necessary CSS and JavaScript files (using the CDN method for simplicity):

<!DOCTYPE html>
<html>
<head>
<title>Glide.js Example</title>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@glidejs/glide@3/dist/css/glide.core.min.css">
</head>
<body>

<div class="glide">
  <div class="glide__track" data-glide-el="track">
    <ul class="glide__slides">
      <li class="glide__slide"><img src="image1.jpg" alt="Image 1"></li>
      <li class="glide__slide"><img src="image2.jpg" alt="Image 2"></li>
      <li class="glide__slide"><img src="image3.jpg" alt="Image 3"></li>
    </ul>
  </div>
</div>

<script src="https://cdn.jsdelivr.net/npm/@glidejs/glide@3/dist/js/glide.min.js"></script>
<script>
  new Glide('.glide').mount();
</script>
</body>
</html>

Remember to replace "image1.jpg", "image2.jpg", and "image3.jpg" with the actual paths to your images. This will create a simple slider. You can then expand this example using the various configuration options detailed elsewhere in this manual.

Core Concepts

Understanding Glide

Glide.js is a lightweight, dependency-free JavaScript library designed to build flexible and performant carousels and sliders. It employs a simple yet powerful API built around a core set of components that work together to create the slider functionality. These components are easily configurable allowing for extensive customization. Glide prioritizes performance and is designed to handle large numbers of slides efficiently. Its modular design enables developers to selectively include only the features needed, further optimizing the size and performance of their projects.

Components Overview

Glide’s functionality is organized around several key components:

The Glide Instance

The Glide instance is the central point of interaction with the library. It’s created using the new Glide(selector, config) constructor.

The instance provides methods to control the slider’s behavior:

Events

Glide triggers several custom events throughout its lifecycle, allowing for integration with other JavaScript code and fine-grained control over the slider’s behavior. These events are dispatched on the Glide instance. You can listen for these events using the standard JavaScript addEventListener method:

Example of listening for an event:

const glide = new Glide('.glide').mount();

glide.on('mounted', () => {
  console.log('Glide mounted!');
});

glide.on('change', () => {
    console.log('Slide changed!');
});

The specific events and their arguments are detailed in the API Reference section of this manual.

Configuration Options

Glide.js offers a wide range of configuration options to customize the slider’s behavior. These options are passed as an object to the Glide constructor. All options are optional, and Glide will use default values if they’re not specified.

Type

Defines the type of slider.

Direction

Specifies the direction of the slider’s movement.

PerView

Determines the number of slides visible at a time in carousel mode.

FocusAt

Specifies the alignment of the visible slides. Only applicable for type: 'carousel'.

Gap

Sets the spacing between slides in pixels.

Bound

Controls whether the slider should stop at the first and last slides.

Hoverpause

Pauses autoplay when the mouse hovers over the slider.

Autoplay

Enables autoplay functionality.

AnimationDuration

Sets the duration of the animation (in milliseconds).

Easing

Specifies the easing function for the animation.

Keyboard

Enables keyboard navigation.

SwipeThreshold

Sets the minimum distance (in pixels) that the user needs to swipe before the slider moves.

DragThreshold

Sets the minimum distance (in pixels) that the user needs to drag before the slider starts dragging.

Peek

Controls how much of the adjacent slides is visible when using type: 'carousel'. It takes either a numerical value for pixels or a percentage string.

Breakpoints

Allows responsive configurations by defining different settings for various screen sizes. This option takes an object where keys are breakpoints (in pixels) and values are configuration objects.

Rewind

Enables rewinding (looping back to the beginning) at the end of the slider.

Throttle

Sets the time in milliseconds to limit the frequency of events such as move. This helps to improve performance in scenarios with rapid changes. * throttle: 100 (default): Events are throttled to at most 100ms intervals

StartAt

Specifies the index of the slide to start on.

Glide.js provides several ways to navigate through the slides, ranging from automatically generated controls to programmatic manipulation.

Glide automatically generates navigation arrows if you include the appropriate HTML structure in your slider’s markup. This requires the addition of <button> elements within a container with the class glide__arrows.

<div class="glide">
  <div class="glide__track" data-glide-el="track">
    <ul class="glide__slides">
      <!-- Slides -->
    </ul>
  </div>
  <div class="glide__arrows" data-glide-el="controls[nav]">
    <button class="glide__arrow glide__arrow--prev" data-glide-dir="<">prev</button>
    <button class="glide__arrow glide__arrow--next" data-glide-dir=">">next</button>
  </div>
</div>

The data-glide-el="controls[nav]" attribute associates the arrows with Glide.js’s navigation controls. The data-glide-dir="<" and data-glide-dir=">" attributes are essential for the correct functioning of the buttons, indicating the direction of movement. The text content (“prev” and “next” in this example) is only for visual representation.

Similar to arrows, navigation bullets (pagination) can be added. Again, specific HTML structure is needed:

<div class="glide">
  <div class="glide__track" data-glide-el="track">
    <ul class="glide__slides">
      <!-- Slides -->
    </ul>
  </div>
  <div class="glide__bullets" data-glide-el="controls[nav]">
    <button class="glide__bullet" data-glide-dir="=1"></button>
    <button class="glide__bullet" data-glide-dir="=2"></button>
    <button class="glide__bullet" data-glide-dir="=3"></button>
    <!-- Add more bullets as needed -->
  </div>
</div>

Glide.js will automatically generate the correct number of bullets based on the number of slides. Each bullet’s data-glide-dir attribute should be set to "=n" where n represents the slide’s index (starting from 1). Note that data-glide-el="controls[nav]" is again used to associate these controls with Glide. The CSS for styling bullets is not included in core Glide CSS. You’ll need to add your own custom styles.

Go to Specific Slide

You can programmatically move to a specific slide using the go() method of the Glide instance. The argument is the slide index (0-based).

const glide = new Glide('.glide').mount();
glide.go(2); // Goes to the third slide (index 2)

Previous & Next Slides

The prev() and next() methods allow moving to the previous and next slides respectively.

const glide = new Glide('.glide').mount();
glide.prev(); // Goes to the previous slide
glide.next(); // Goes to the next slide

Programmatic Control

In addition to go(), prev(), and next(), the Glide instance offers other methods for programmatic control:

These methods provide complete control over the slider’s behavior from your JavaScript code, allowing for seamless integration with other parts of your application. Remember to always check for the existence of a Glide instance before calling its methods.

Advanced Techniques

This section covers more complex usage scenarios and techniques for extending Glide.js’s functionality.

Customizing the Appearance

Glide.js provides a minimal set of CSS classes for styling. To achieve a unique look and feel, you’ll likely need to extensively customize the CSS. Target the relevant classes (e.g., .glide, .glide__track, .glide__slide, .glide__arrow, .glide__bullet) to modify colors, fonts, spacing, and other visual elements. Remember that the structure of the HTML is crucial for Glide’s functionality; avoid modifying the core HTML structure of the slider unless absolutely necessary. You can also leverage CSS frameworks (like Bootstrap or Tailwind CSS) to integrate Glide.js more seamlessly into your design system.

Working with Multiple Instances

Glide.js easily supports multiple instances on a single page. Simply create separate Glide instances for each slider element, each with its own unique selector and configuration:

const glide1 = new Glide('.glide1', { type: 'carousel', perView: 3 }).mount();
const glide2 = new Glide('.glide2', { autoplay: 2000 }).mount();

Each slider needs its own unique container element (e.g., .glide1, .glide2). This approach allows for independent control and configuration of multiple sliders on the same page.

Integrating with Other Libraries

Glide.js is designed to be lightweight and non-intrusive. It can typically be integrated with other JavaScript libraries without conflicts. However, be mindful of potential naming collisions or conflicting event handlers. If necessary, namespace your Glide code or carefully check for potential overlaps with other libraries’ functionalities. For example, integrating with a parallax library might require adjusting the timing or event handling to coordinate the animations correctly.

Handling Events

Glide.js dispatches several custom events during its operation. These events allow for dynamic updates and interactions based on slider state changes (e.g., slide change, mounting, destroying). Utilize the on() method to register event listeners:

const glide = new Glide('.glide').mount();

glide.on('mounted', () => {
  console.log('Glide is mounted!');
});

glide.on('run', () => {
  console.log('Slider is running!');
});

glide.on('change', () => {
  console.log('Active slide changed!');
});

glide.on('destroy', () => {
  console.log('Glide is destroyed!');
});

This provides a mechanism to trigger other actions or update other parts of your application in response to slider events.

Extending Glide with Plugins

While Glide.js is highly configurable, you can extend its capabilities by creating custom plugins. Glide’s architecture allows for adding new features without modifying the core library. A plugin would typically consist of additional methods or functionality that integrate with the Glide instance. The plugin would be registered with the Glide instance using the addPlugin() method. The detailed implementation of plugin creation is beyond the scope of this section but is further described in the advanced documentation (link to advanced documentation). This powerful mechanism allows extending Glide to handle custom behaviors, animations, and UI interactions.

Troubleshooting

This section provides guidance on resolving common issues and debugging Glide.js implementations.

Common Issues

Debugging Tips

Error Handling

Glide.js itself doesn’t throw many explicit errors. Most problems manifest as the slider not behaving as expected (e.g., not showing slides, navigation not working). Therefore, focus on the debugging tips mentioned above. The browser’s JavaScript console is your primary tool for identifying the root cause of unexpected behavior. If the console provides insufficient information, try creating more verbose logging statements in your JavaScript code to track the values of variables and the execution flow to help track down the source of the problem.

API Reference

This section provides a detailed reference for the Glide.js API, including instance methods, properties, and events.

Glide Instance Methods

The Glide instance exposes several methods to control the slider’s behavior. These methods are called on the instance object created by new Glide(selector, config).mount().

Glide Instance Properties

The Glide instance exposes some properties for accessing slider information. These properties should be considered read-only; modifying them directly may lead to unexpected behavior.

Event API

Glide.js dispatches custom events on the Glide instance. You can listen for these events using the on() method. The event object passed to the handler function may contain additional data depending on the event.

Remember to consult the latest Glide.js documentation for the most up-to-date API reference and any potential changes. The specific details and availability of methods and properties may vary depending on the Glide.js version.