DOCSEARCHbyAlgolia
Submit Docs

featherlight

repository·master·Indexed 24 days ago

https://github.com/noelboss/featherlight

A lightweight jQuery lightbox plugin (version 1.7.14) that is simple, flexible, and responsive. It supports images, Ajax, iFrames, and custom DOM content with a small footprint of less than 4kB. The library features automatic binding via data attributes, customizable configuration options, lifecycle hooks, and an optional Gallery extension.

Tokens
6.7K
Snippets
15
Records
31
Agent score
82%

What's inside featherlight

  1. Gallery events and CSS classes

    master

    The Featherlight Gallery provides the following hooks for interaction and styling:

    Custom Events The gallery responds to previous and next custom events to navigate between images.

    CSS Classes The gallery applies specific classes to the current slide to indicate position:

    • .featherlight-first-slide: Applied when the current slide is the first in the gallery.
    • .featherlight-last-slide: Applied when the current slide is the last in the gallery.

  2. How content filters work in Featherlight

    master

    Featherlight uses heuristics to automatically determine the type of content to display (e.g., files ending in .gif are treated as images).

    If heuristics fail, you can explicitly specify a contentFilter using the data-featherlight attribute or via JavaScript.

    Explicitly specifying a filter:

    • HTML: <a href="path/to/file" data-featherlight="image">Link</a>
    • JavaScript: $('#element').featherlight('image'); or $('#element').featherlight({type: {image: true}});

    Note on 'text' filter: The text filter has no automatic heuristic and must be specified explicitly: <a href="Hello" data-featherlight="text">Example</a>.

    /* Explicitly forcing an image type via JS */
$('#force_as_image').featherlight('image');
// or
$('#force_as_image').featherlight({type: {image: true}});

/* Explicitly forcing an image type via JS with a URL */
$('#force_as_image2').featherlight('photo_without_extension', {type:{image: true}});

  3. Install Featherlight

    master

    Featherlight requires jQuery (version 1.7.0 or higher, regular version) and its own CSS file for styling. It is recommended to include the JavaScript files at the bottom of your page before the closing </body> tag.

    Note on CSS: Featherlight uses unspecific CSS selectors to allow easy overwriting. If your project uses highly specific global CSS definitions (like IDs), they may conflict with Featherlight's styling.

    <!-- Include CSS in the <head> -->
<link href="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.min.css" type="text/css" rel="stylesheet" />

<!-- Include jQuery and Featherlight at the bottom of the <body> -->
<script src="//code.jquery.com/jquery-latest.js"></script>
<script src="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.min.js" type="text/javascript" charset="utf-8"></script>

  4. Enable swipe support for Featherlight Gallery on mobile

    master
    Featherlight Gallery does not include touch swipe logic by default. To enable swipe navigation on mobile and tablet devices, you must include a supported swipe library (such as detect_swipe) in your project.

  5. Install the Featherlight Gallery extension

    master

    The Gallery functionality is an extension and must be included separately. Include the gallery CSS and JS files after the core Featherlight files.

    Installation via CDN:

    <!-- Core Featherlight -->
<link href="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.min.css" type="text/css" rel="stylesheet" />

<!-- Gallery Extension -->
<link href="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.gallery.min.css" type="text/css" rel="stylesheet" />

<script src="//code.jquery.com/jquery-latest.js"></script>
<script src="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.min.js" type="text/javascript" charset="utf-8"></script>
<script src="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.gallery.min.js" type="text/javascript" charset="utf-8"></script>
    <link href="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.min.css" type="text/css" rel="stylesheet" />
<link href="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.gallery.min.css" type="text/css" rel="stylesheet" />

<script src="//code.jquery.com/jquery-latest.js"></script>
<script src="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.min.js" type="text/javascript" charset="utf-8"></script>
<script src="//cdn.jsdelivr.net/npm/featherlight@1.7.14/release/featherlight.gallery.min.js" type="text/javascript" charset="utf-8"></script>

  6. Use Featherlight via data attributes

    master

    By default, Featherlight automatically binds to any element containing the data-featherlight attribute. The value of this attribute determines what content is opened in the lightbox.

    Supported Content Types:

    • DOM Selector: Use a selector (e.g., #id) to open an existing element on the page.
    • Image: Provide a direct link to an image file.
    • Ajax: Provide a URL and an optional selector to extract specific content from the response.
    • Inline DOM: Provide raw HTML strings directly in the attribute.

    Triggering via href and keywords:

    You can also use the href attribute in combination with the data-featherlight keyword (image or ajax) or specific data attributes like data-featherlight-ajax or data-featherlight-type.

    <!-- Open an existing element via selector -->
<a href="#" data-featherlight="#mylightbox">Open element in lightbox</a>
<div id="mylightbox">This div will be opened in a lightbox</div>

<!-- Open an image -->
<a href="#" data-featherlight="myimage.png">Open image in lightbox</a>
<a href="myimage.png" data-featherlight="image">Open image in lightbox</a>

<!-- Open Ajax content -->
<a href="#" data-featherlight="myhtml.html .selector">Open ajax content in lightbox</a>
<a href="myhtml.html .selector" data-featherlight="ajax">Open ajax content in lightbox</a>
<a href="#" data-featherlight-ajax="myhtml.html .selector">Open ajax content in lightbox</a>
<a href="#" data-featherlight="myhtml.html .selector" data-featherlight-type="ajax">Open ajax content in lightbox</a>

<!-- Open inline DOM -->
<a href="#" data-featherlight="<p>Fancy DOM Lightbox!</p>">Open some DOM in lightbox</a>

  7. Configure Featherlight options

    master

    Featherlight is highly configurable. You can set options in three ways:

    1. When calling the constructor: Pass an options object directly to the .featherlight() method.
    2. Via HTML data attributes: Use data-featherlight-* attributes on the triggering element. For example, <a data-featherlight-close-on-esc="false"> is equivalent to {closeOnEsc: false}.
    3. Global defaults: Modify $.featherlight.defaults to apply settings to all future instances.

    Commonly used options include openSpeed, closeSpeed, closeOnEsc, and closeOnClick (which accepts 'background', 'anywhere', or false).

  9. Configure Featherlight via data attributes

    master

    Featherlight supports configuring individual instances using data-featherlight-* attributes on the triggering element. These attributes are automatically parsed and camelCased. For example, data-featherlight-open-speed="500" will set the openSpeed option to 500.

    Note: For callback functions (like beforeOpen), the attribute value must be a valid JavaScript string that can be evaluated.

  10. Use the Featherlight Gallery extension

    master

    The Featherlight Gallery extension allows you to group multiple items into a single lightbox session, enabling users to navigate through a collection of images or content using 'next' and 'previous' controls.

    To use it, you can either call the .featherlightGallery() method on a jQuery object or use the data-featherlight-gallery attribute for automatic binding.

    Prerequisites:

    1. jQuery must be loaded.
    2. Featherlight (the core plugin) must be loaded before the Gallery extension.
    3. For touch/swipe support, a compatible swipe library (like Hammer.js or jQuery's swipe events) must be included.

  11. Use automatic gallery binding with HTML data attributes

    master

    If you want to use the default autoBind behavior, you can mark a container with the data-featherlight-gallery attribute. You can also use data-featherlight-filter to specify which elements within that container should be included in the gallery (e.g., a tags).

    <section
  data-featherlight-gallery
  data-featherlight-filter="a"
>
  <h1>This is a gallery</h1>
  <a href="photo_large.jpg"><img src="photo_thumbnail.jpg"></a>
  <a href="other_photo_large.jpg"><img src="other_photo_thumbnail.jpg"></a>
</section>

  12. Open content in an iframe

    master

    Use the iframe keyword to load content inside an iframe. By default, the iframe size is 300x150.

    Iframe Attributes: You can control iframe behavior using data-featherlight-iframe-* attributes in HTML or iframe* options in JavaScript. Supported attributes include: allow, allowfullscreen, frameborder, height, longdesc, marginheight, marginwidth, mozallowfullscreen, name, referrerpolicy, sandbox, scrolling, src, srcdoc, style, webkitallowfullscreen, width.

    Common usage:

    • Set dimensions: data-featherlight-iframe-height="640" data-featherlight-iframe-width="480"
    • Set styles: data-featherlight-iframe-style="border:none"
    • Via JS: $.featherlight({iframe: 'url.html', iframeWidth: 500, iframeHeight: 300});
    <a href="http://www.example.com" data-featherlight="iframe">Open example.com in an iframe</a>

<!-- Example with dimensions and styles -->
<a href="http://www.youtube.com/embed/f0BzD1zCye0?rel=0&amp;autoplay=1" 
   data-featherlight="iframe" 
   data-featherlight-iframe-width="640" 
   data-featherlight-iframe-height="480" 
   data-featherlight-iframe-frameborder="0" 
   data-featherlight-iframe-allow="autoplay; encrypted-media" 
   data-featherlight-iframe-allowfullscreen="true">
   <img src="http://img.youtube.com/vi/f0BzD1zCye0/0.jpg" alt="" />
</a>