Featherlight is a lightweight and highly customizable JavaScript library designed to create elegant and responsive lightbox-style image galleries and content viewers. It focuses on simplicity and performance, minimizing the impact on your website’s loading time and resources. Featherlight is ideal for showcasing images, videos, or any other HTML content in a clean and unobtrusive modal window. It’s easy to integrate into existing projects and requires minimal coding.
Featherlight can be included in your project via several methods:
Download: Download the latest version of Featherlight from https://noelboss.github.io/featherlight/. Include the featherlight.min.js and featherlight.min.css files in your project’s <head> section.
CDN: Use a CDN link to include Featherlight in your project. You can find suitable CDN links on sites like jsDelivr or cdnjs.:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/featherlight/1.7.13/featherlight.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/featherlight/1.7.13/featherlight.min.js"></script>npm install featherlightRemember to include the CSS file in your HTML <head> and the JS file before the closing </body> tag for proper functionality.
This example shows how to create a simple image lightbox:
<!DOCTYPE html>
<html>
<head>
<title>Featherlight Example</title>
<link rel="stylesheet" href="featherlight.min.css">
</head>
<body>
<a href="image1.jpg" data-featherlight="image1.jpg">Image 1</a>
<a href="image2.jpg" data-featherlight="image2.jpg">Image 2</a>
<script src="featherlight.min.js"></script>
</body>
</html>Replace "image1.jpg" and "image2.jpg" with the actual paths to your images. Featherlight automatically detects the href attribute and opens the link in a lightbox. You can customize this further using various options and parameters detailed in the advanced usage section.
Featherlight offers several ways to open a lightbox:
1. Using HTML links: The simplest method is to wrap your content links with <a> tags and add the data-featherlight attribute. The value of this attribute can be a URL, a selector, or a function returning the content to be displayed in the lightbox.
<a href="image.jpg" data-featherlight="image.jpg">View Image</a>
<a href="#my-content" data-featherlight="#my-content">View Content</a>
<a href="#" data-featherlight="function(){return '<h1>Hello!</h1>';}">View Custom HTML</a>2. Programmatically: You can open a lightbox programmatically using JavaScript:
Featherlight.open('image.jpg');
Featherlight.open('#my-content');
Featherlight.open(function(){ return '<h1>Hello!</h1>'; });
// or with options
Featherlight.open('image.jpg', {
afterOpen: function() { console.log('Lightbox opened!'); }
});Replace "image.jpg" and "#my-content" with your actual content. The function example demonstrates creating dynamic content within the lightbox. For elements, make sure they exist on the page before the script that opens the lightbox is executed.
Featherlight provides several methods to close the lightbox:
Clicking the close button: Featherlight automatically adds a close button to the lightbox. Clicking this button will close the lightbox.
Pressing the Escape key: Pressing the Escape key on your keyboard will close the lightbox.
Programmatically: Use the following JavaScript code to close the lightbox:
Featherlight.close();This will close the currently open lightbox.
close event: Close the lightbox in response to a custom event. See the Event Handling section below for details.Featherlight offers several events you can listen for and use to trigger custom actions:
afterOpen: Triggered after the lightbox has been opened.beforeClose: Triggered before the lightbox is closed; use to prevent closure if necessary (return false to prevent closing).close: Triggered after the lightbox has been closed.beforeOpen: Triggered before the lightbox is opened; use to prevent opening if necessary (return false to prevent opening).load: Triggered when the content inside the lightbox has fully loaded.Here’s how to listen for these events:
Featherlight.open('image.jpg', {
afterOpen: function() { console.log('Lightbox opened!'); },
beforeClose: function() {
if (confirm("Are you sure you want to close?")) {
return true; // Allow closing
} else {
return false; // Prevent closing
}
},
close: function() { console.log('Lightbox closed!'); }
});
// alternative using jQuery:
$('a[data-featherlight]').featherlight({
afterOpen: function() { console.log('Lightbox opened!'); }
});Remember to replace "image.jpg" with your actual content.
Featherlight incorporates several features to enhance accessibility:
aria-modal, aria-hidden, role="dialog") to improve screen reader compatibility and overall accessibility.These features ensure that Featherlight is usable by a wider audience, including users who rely on assistive technologies. Always test your implementation with assistive technologies to ensure optimal accessibility.
Featherlight’s appearance is easily customizable through CSS. The library uses a well-structured CSS architecture, making it straightforward to override default styles. The main CSS class for the lightbox is featherlight. You can target specific elements within the lightbox using classes like .featherlight-content, .featherlight-close, and .featherlight-inner.
For example, to change the background color of the lightbox:
.featherlight {
background-color: #f0f0f0; /* Change to your desired color */
}To customize the close button:
.featherlight-close {
color: red; /* Change the color of the close button */
font-size: 20px; /* Adjust the size */
}Remember to include your custom CSS after the Featherlight CSS file to override the default styles.
You can customize the content displayed within the lightbox in several ways:
<a> tag linking to your lightbox content:<a href="image.jpg" data-featherlight="image.jpg" data-my-custom-attribute="My custom value">View Image</a>Access this data attribute using Javascript within the lightbox’s callbacks (see Using Callbacks section).
Featherlight.open(function() {
return '<div><h1>Dynamic Content</h1><p>This content is generated dynamically.</p></div>';
});<a href="http://example.com" data-featherlight-iframe="true">View External Content</a>This will open the link within an iframe inside the lightbox. Note that the data-featherlight-iframe attribute is used to indicate iframe content.
You can add custom controls to your lightbox using Javascript and manipulating the DOM. After the lightbox opens (using the afterOpen callback), you can append your custom elements to the lightbox container.
Featherlight.open('image.jpg', {
afterOpen: function() {
const customButton = document.createElement('button');
customButton.textContent = 'My Custom Button';
customButton.addEventListener('click', function() {
// Add your custom functionality here
alert('Custom button clicked!');
});
this.$instance.find('.featherlight-inner').append(customButton);
}
});This code adds a button to the lightbox after it’s opened. Replace this example with your own custom HTML and functionality.
Featherlight provides several options that you can configure to customize its behavior:
afterOpen: Callback function executed after the lightbox opens.beforeClose: Callback function executed before the lightbox closes. Return false to cancel closure.beforeOpen: Callback function executed before the lightbox opens. Return false to cancel opening.close: Callback function executed after the lightbox closes.closeOnEscape: Boolean (default: true) - Whether to close the lightbox when the Escape key is pressed.closeOnClick: Boolean (default: true) - Whether to close the lightbox when clicking outside the lightbox content.loading: String (default: ’’) - Content to display while the lightbox is loading.root: String (default: ‘body’) - Where the lightbox should be appended. Useful for specific page layouts.variant: String (default: ’’) - Adds a CSS class for styling variations (e.g., featherlight featherlight-variant-dark).persist: Boolean (default: false) - Prevents the lightbox from being automatically closed after the content is viewed.To use these options, pass them as an object to Featherlight.open() or as a parameter to $.featherlight().
Featherlight.open('image.jpg', {
closeOnEscape: false,
afterOpen: function() { console.log('Lightbox opened!'); }
});Callbacks allow you to execute custom code at specific points in the lightbox lifecycle. Featherlight provides the afterOpen, beforeClose, beforeOpen, close, and load callbacks.
These callbacks receive the lightbox instance as this allowing access to methods and properties. For example, this.$instance refers to the lightbox’s jQuery element. You can use this to manipulate the lightbox’s DOM elements. See the examples within the “Event Handling” and “Adding Custom Controls” sections above. Use callbacks to integrate Featherlight seamlessly into your application’s workflow.
Featherlight supports opening multiple lightboxes simultaneously. Each lightbox instance is independent, allowing for flexible use cases. Simply call Featherlight.open() multiple times, each with its own content. Featherlight manages the instances internally, ensuring proper behavior even when overlapping. The close() method closes only the most recently opened lightbox unless specified otherwise. Consider using unique identifiers or namespaces to easily manage multiple lightboxes within a complex application.
Featherlight is designed to be compatible with many JavaScript libraries. However, potential conflicts may arise due to overlapping functionality (such as event handling or DOM manipulation). When integrating with other libraries, ensure that you properly load the scripts in the correct order and consider using namespaces to avoid naming collisions. Test your integration thoroughly to identify and resolve any conflicts that may occur. If using jQuery, Featherlight’s jQuery plugin offers a seamless integration, simplifying the setup and usage.
While Featherlight is robust, certain situations may require specific handling:
Failed Content Loading: If the content fails to load (e.g., a broken image link), you can use the load callback to detect and handle errors gracefully. Within this callback, you can display an error message or take other corrective actions.
Content Size Issues: Very large images or content might exceed the available viewport. You can use CSS to define overflow behavior or implement custom scrolling within the lightbox to address this.
Browser Compatibility: While Featherlight aims for broad browser support, some very old or obscure browsers might require specific handling or might not be fully supported. Always test thoroughly across various browsers and versions to ensure consistent behavior.
Accessibility Considerations: Ensure sufficient contrast between text and background colors in the lightbox, add appropriate ARIA attributes, and implement keyboard navigation for improved accessibility.
For optimal performance, especially when dealing with many images or large content:
Lazy Loading: Implement lazy loading techniques to defer loading of images or content until they are needed, improving initial page load times.
Image Optimization: Optimize your images to reduce their file size without significant quality loss.
Caching: Utilize browser caching mechanisms to reduce redundant network requests.
Minification and Compression: Minify and compress your JavaScript and CSS files to reduce their size, improving download times.
Avoid Unnecessary DOM Manipulation: Minimize the number of times you manipulate the DOM within the lightbox callbacks, as frequent DOM changes can impact performance.
Featherlight’s architecture is designed to be extensible. You can create custom plugins to add new features or modify existing behavior. This typically involves extending the core functionality using the provided callbacks and adding your own custom logic. You would then register this plugin, making it available to use throughout your application. Create a separate JavaScript file for your plugin to maintain a clear and organized structure. Keep your plugin’s code concise and well-documented for easy maintenance and future use. Thoroughly test your custom plugin to ensure it functions correctly and integrates seamlessly with the rest of Featherlight.
The Featherlight constructor is used to initialize a new lightbox instance. While generally not called directly (as it’s typically handled internally by the library), understanding its purpose is beneficial for advanced usage and custom plugin development. The constructor takes an optional configuration object as an argument which will be passed through to the Featherlight.open method if called directly from the constructor. For standard use cases, direct instantiation isn’t necessary; instead, utilize the Featherlight.open() method or the jQuery plugin.
Featherlight provides several methods for manipulating lightbox instances:
Featherlight.open(content, options): Opens a new lightbox with the specified content and optional options. content can be a string (URL, selector), a function returning content, or a DOM element. options is an object containing configuration settings (see Options section). This is the primary method for creating and showing lightboxes.
Featherlight.close(): Closes the currently active lightbox.
Featherlight.current(): Returns the currently active Featherlight instance. This allows you to interact directly with the active lightbox. Returns null if no lightbox is open.
Featherlight triggers several custom events throughout its lifecycle. These events are useful for adding custom functionality and extending the library’s behavior. These events are detailed in the “Core Functionality” and “Customization Options” sections, but are summarized here:
beforeOpen: Triggered just before a lightbox opens. Returning false from a handler prevents the lightbox from opening.afterOpen: Triggered after a lightbox has opened.beforeClose: Triggered just before a lightbox closes. Returning false from a handler prevents the lightbox from closing.close: Triggered after a lightbox has closed.load: Triggered after the lightbox content has finished loading.These events are accessible via the on method on the instance (e.g., featherlightInstance.on('afterOpen', myFunction)), or via the options object when calling Featherlight.open.
Featherlight offers a range of options for customizing its behavior. These options can be passed as a second argument to Featherlight.open(). Key options include:
afterOpen: Callback function executed after the lightbox is opened.beforeClose: Callback function executed before the lightbox is closed. Return false to prevent closing.beforeOpen: Callback function executed before the lightbox is opened. Return false to prevent opening.close: Callback function executed after the lightbox is closed.closeOnEscape: Boolean (default: true). Whether to close the lightbox when the Escape key is pressed.closeOnClick: Boolean (default: true). Whether to close the lightbox when clicking outside the lightbox content.loading: String (default: ''). Content to display while the lightbox is loading.root: String (default: 'body'). Where to append the lightbox in the DOM.variant: String (default: ''). Adds a CSS class to the lightbox for styling variations.persist: Boolean (default: false). Prevents the lightbox from automatically closing after content is viewed.filter: String (default: ‘a’). The CSS selector to use for identifying links that trigger Featherlight.content: The content to be displayed, used internally in the initialization.A full example of using options:
Featherlight.open('#my-content', {
closeOnEscape: false,
afterOpen: function() { console.log('Lightbox opened!'); },
variant: 'dark'
});Remember to consult the latest Featherlight documentation for the most up-to-date list of options and their descriptions.
data-featherlight attribute.src attribute is correctly set and that the source URL allows embedding.console.log() statements: Add console.log() statements to your code to track variable values and the execution flow..featherlight class and its child elements to customize colors, fonts, and other visual aspects. See the “Customization Options” section of this manual.load event callback to check for errors. If the content fails to load, you can handle it gracefully within the callback (e.g., display an error message).Featherlight.open() multiple times. Featherlight handles multiple instances correctly.Remember to check the official Featherlight documentation and GitHub repository for the most current information and solutions to any issues you encounter.
We welcome contributions to Featherlight! Whether you’re reporting bugs, suggesting features, or submitting code changes, your involvement is valuable. Please follow these guidelines to ensure a smooth and efficient contribution process.
When reporting a bug, please provide the following information:
We encourage you to suggest new features for Featherlight. When suggesting a feature, please provide:
If you’re submitting a pull request (PR), please follow these guidelines:
fix-bug-lightbox-closing, feature-custom-controls).We will review your pull request and provide feedback.
Featherlight uses a consistent coding style to maintain readability and maintainability. Please adhere to the following guidelines when contributing code:
Please ensure your code follows these guidelines before submitting a pull request. Consistency in code style makes it easier for others to review and understand your contributions. Refer to existing code in Featherlight’s source as a guide for style.