Magnific Popup - Documentation

Getting Started

This section guides you through setting up and using Magnific Popup.

Installation

Magnific Popup can be installed in several ways:

  1. Download: Download the latest release from the https://github.com/dimsemenov/Magnific-Popup. Extract the contents and include the necessary files (magnific-popup.css and magnific-popup.js) in your project.

  2. CDN: Use a CDN like jsDelivr or cdnjs to include the files directly in your HTML. For example, using jsDelivr:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/magnific-popup@1.1.0/dist/magnific-popup.css">
<script src="https://cdn.jsdelivr.net/npm/magnific-popup@1.1.0/dist/jquery.magnific-popup.min.js"></script>

Note: Remember to replace 1.1.0 with the latest version number. You’ll also need jQuery included in your project for Magnific Popup to function. Ensure jQuery is loaded before the Magnific Popup script.

  1. npm/yarn: If you’re using a package manager, install it via npm or yarn:
npm install magnific-popup
# or
yarn add magnific-popup

Then, import the necessary files in your application’s build process (e.g., using Webpack or Parcel).

Basic Usage

After installation, initializing Magnific Popup is straightforward. You’ll need to select the elements you want to make into popups and call the .magnificPopup() method on them.

$(document).ready(function() {
  $('.image-popup-vertical-fit').magnificPopup({
    type: 'image',
    mainClass: 'mfp-img-mobile',
    image: {
      verticalFit: true
    }
  });
});

This code snippet targets elements with the class image-popup-vertical-fit, sets the popup type to image, applies a specific main class for styling, and ensures vertical image fitting. Replace $('.image-popup-vertical-fit') with your selector and adjust the options as needed. Refer to the options documentation for a complete list of available settings.

Markup Requirements

Magnific Popup doesn’t require any specific HTML structure, but you need to select the elements that will trigger the popup using a suitable selector (e.g., class, ID). It’s recommended to use a class for consistency and easier management. For example:

<a href="image1.jpg" class="image-popup-vertical-fit">
  <img src="thumbnail1.jpg" alt="Image 1">
</a>
<a href="image2.jpg" class="image-popup-vertical-fit">
  <img src="thumbnail2.jpg" alt="Image 2">
</a>

This markup links each image to its larger version and applies the class image-popup-vertical-fit, which is targeted by the JavaScript code. The href attribute specifies the large image URL. You can also use different content types besides images, as explained in the detailed options documentation.

CSS Integration

Magnific Popup includes its own CSS file (magnific-popup.css). Make sure this CSS file is included in your project’s stylesheet. It provides the default styling for the popup. You can customize its appearance by creating a custom CSS file and overriding the default styles. Remember to include your custom CSS file after magnific-popup.css to ensure your styles take precedence. You can also use the mainClass option to apply additional custom CSS classes for finer control over individual popups.

Core Functionality

This section details the core functionalities of Magnific Popup.

Opening the Popup

Magnific Popup opens automatically when a selected element is clicked. The opening behavior is determined by the options you provide when initializing the plugin. The most basic initialization involves selecting elements and calling the .magnificPopup() method:

$(document).ready(function() {
  $('.my-popup-link').magnificPopup({
    type: 'image' // or 'inline', 'ajax', 'iframe', etc.
  });
});

This code will initialize Magnific Popup for elements with the class my-popup-link, setting the popup type to ‘image’. The type option dictates how the content is handled (see the “Content Types” section in a later chapter for details). Clicking an element with the my-popup-link class will open the popup.

Closing the Popup

Magnific Popup provides several ways to close a popup:

Event Handling

Magnific Popup triggers several events throughout its lifecycle. You can listen for these events using jQuery’s .on() method to perform custom actions. Here are a few key events:

Example: Preventing the popup from closing if a condition isn’t met:

$(document).ready(function() {
  $('.my-popup-link').magnificPopup({
    type: 'image',
    beforeClose: function(e) {
      if (!confirm('Are you sure you want to close?')) {
        e.preventDefault();
      }
    }
  });
});

API Methods

Magnific Popup provides several API methods for controlling the popup’s behavior:

Important Note: Many of these methods are accessed through the $.magnificPopup.instance object, which represents the currently active popup. Always verify that a popup is actually open before using these methods, otherwise, you may encounter errors.

Remember to consult the official documentation for the most up-to-date information on options, events, and API methods.

Image Galleries

Magnific Popup excels at creating beautiful and functional image galleries. This section details how to implement and customize them.

Creating an image gallery is straightforward. Instead of initializing Magnific Popup on individual image links, you select all links belonging to the gallery and initialize it as a gallery using the delegate option and setting the type to image. The gallery option automatically enables gallery functionality. Ensure all image links share a common selector for efficient targeting.

<div class="gallery-container">
  <a href="image1.jpg" class="gallery-item"><img src="thumb1.jpg" alt="Image 1"></a>
  <a href="image2.jpg" class="gallery-item"><img src="thumb2.jpg" alt="Image 2"></a>
  <a href="image3.jpg" class="gallery-item"><img src="thumb3.jpg" alt="Image 3"></a>
</div>
$(document).ready(function() {
  $('.gallery-container').magnificPopup({
    delegate: 'a.gallery-item', // child items selector, by clicking on it will open magnificPopup
    type: 'image',
    gallery:{
      enabled:true
    }
  });
});

This code sets up a gallery where clicking on any .gallery-item link opens the corresponding image in a Magnific Popup gallery. The delegate option specifies that the popup should be initialized on the children of .gallery-container that match the selector a.gallery-item.

Magnific Popup automatically provides navigation arrows for moving between images in a gallery. Users can click these arrows or use the left/right arrow keys to navigate. The navigation behavior is handled automatically through the gallery options.

Thumbnail Display

Magnific Popup doesn’t inherently display thumbnails within the gallery itself. However, you can create a custom thumbnail display using JavaScript and potentially integrating with external libraries if needed for more sophisticated thumbnail displays.

Several options control the gallery’s behavior:

Using Different Image Sources

While the examples above use direct image URLs, you can use other sources, such as data URLs or images loaded dynamically via AJAX. Adjust the type option and potentially the image.src option in more complex setups for this. For example, If your images are loaded dynamically from an AJAX call, you would handle the image URLs within the ajax options rather than directly in the link’s href attribute. Ensure that the image URLs are correctly resolved in such a dynamic situation.

Remember to consult the official Magnific Popup documentation for the most complete and up-to-date information on gallery options and usage.

HTML Content Popups

Magnific Popup easily handles popups containing HTML content, whether it’s pre-existing on the page or loaded dynamically.

Creating Content Popups

To create a popup displaying existing HTML content, set the type option to inline. This type of popup refers to an element already present in your HTML. You’ll need to provide a selector targeting that element using the inline option.

<a href="#my-content" class="popup-link">Open Popup</a>
<div id="my-content" style="display:none;">
  <h2>This is my popup content</h2>
  <p>This is some example text.</p>
</div>
$(document).ready(function() {
  $('.popup-link').magnificPopup({
    type: 'inline',
    midClick: true, // Allow opening on middle click
    inline:{
      target:'#my-content'
    }
  });
});

This code opens a popup displaying the content of the element with the ID my-content. The style="display:none;" hides the content until the popup opens. Note the use of inline.target to properly target the inline content. The midClick option enables opening the popup when the user clicks the link with the middle mouse button.

Dynamic Content Loading

For dynamic content, use the ajax type. Specify the URL to fetch the content from using the ajax.url option.

$(document).ready(function() {
  $('.popup-link').magnificPopup({
    type: 'ajax',
    ajax: {
      url: 'my-popup-content.html'
    }
  });
});

This loads content from my-popup-content.html into the popup. This file should contain the HTML you want displayed.

Content Styling

Styling HTML content popups is done using standard CSS. You can add custom CSS classes to the popup’s content or use inline styles to customize the appearance. Magnific Popup provides CSS classes that you can use for styling (see the CSS documentation for a complete list).

For example:

<div id="my-content" style="display:none;" class="my-custom-popup-class">
  <!-- Content -->
</div>

Then style the .my-custom-popup-class class in your CSS file.

Iframe Integration

To display content from an external website or an iframe, use the iframe type.

$(document).ready(function() {
  $('.popup-link').magnificPopup({
    type: 'iframe',
    iframe: {
      markup: '<div class="mfp-iframe-scaler">'+
                '<div class="mfp-close"></div>'+
                '<iframe class="mfp-iframe" src="http://www.example.com" frameborder="0" allowfullscreen></iframe>'+
              '</div>', // HTML markup of popup, `src` attribute will be replaced
      srcAction: 'iframe_src', // Templating for src
      patterns: {
        youtube: {
          index: 'youtube.com/', // String that detects type of video (in this case YouTube). Simply via url
          id: 'v=', // id parameter name
          src: '//www.youtube.com/embed/%id%?autoplay=1' // URL that will be set as src attribute
        }
      }
    }
  });
});

This will open a popup containing an iframe showing the content of http://www.example.com. You can customize the iframe’s appearance using CSS and the iframe.markup option allows for significant customization of the iframe popup’s structure. The example also demonstrates the use of patterns for handling different sources, such as Youtube videos. This approach is particularly useful for embedding videos from various platforms seamlessly. The srcAction option tells Magnific Popup how to update the iframe’s src attribute. Setting it to 'iframe_src' means that the src value from the original link will be used to populate the iframe.

Remember to always check the official Magnific Popup documentation for the most current options and best practices.

Ajax Content Popups

Magnific Popup efficiently handles popups that load content via AJAX requests. This allows for dynamic content updates without requiring a full page reload.

Fetching Content via Ajax

The core of AJAX popup functionality lies in setting the type option to ajax and specifying the URL to fetch the content from using the ajax.url option.

$(document).ready(function() {
  $('.ajax-popup-link').magnificPopup({
    type: 'ajax',
    ajax: {
      url: 'my-ajax-content.php', // URL to fetch content from
      tError: 'Error!', // Error message to display if the request fails
      cursor: 'mfp-ajax-cur', // Custom loading cursor class
      settings: { // additional AJAX settings
        dataType: 'json', // or 'html', 'text', etc.
        data: {param1: 'value1', param2: 'value2'} // Additional data to send with request
      }
    }
  });
});

This code initiates an AJAX request to my-ajax-content.php when a link with the class ajax-popup-link is clicked. The response is then displayed within the Magnific Popup. The tError option allows to specify a custom error message. cursor specifies a custom CSS class to use for the loading cursor. settings allows to specify any additional jQuery AJAX options.

Handling Ajax Errors

When an AJAX request fails, Magnific Popup displays a default error message. You can customize this message using the ajax.tError option (as shown above). You can also handle errors more robustly by using the ajax.error callback function:

$(document).ready(function() {
    $('.ajax-popup-link').magnificPopup({
        type: 'ajax',
        ajax: {
            url: 'my-ajax-content.php',
            error: function(xhr, textStatus, errorThrown) {
                // Handle AJAX errors here.
                console.error("AJAX Error:", textStatus, errorThrown);
                // Display a custom error message to the user, e.g., using an alert or updating the DOM
                alert('An error occurred while loading the content. Please try again later.');
            }
        }
    });
});

This improved example includes an error callback that logs the error details to the console and displays a custom alert message to the user. This offers a more informative experience.

Caching Ajax Responses

By default, Magnific Popup doesn’t cache AJAX responses. To enable caching, you can implement your own caching mechanism. This could involve using browser storage (localStorage or sessionStorage) or a server-side caching solution. For simpler scenarios, the browser’s built-in caching might suffice, depending on your server configuration and the cache setting in your AJAX request. However, you should design your caching strategy carefully to ensure data integrity and freshness. For complex scenarios or if you need fine-grained control, a custom caching solution is recommended.

Customizing Ajax Behavior

The ajax option accepts additional jQuery AJAX settings (via the settings property). This allows fine-grained control over the AJAX request, such as setting custom headers, specifying the dataType, or handling different HTTP methods (POST, PUT, etc.).

ajax: {
  url: 'my-ajax-content.php',
  settings: {
    method: 'POST',
    data: { someData: 'someValue' },
    headers: { 'X-Custom-Header': 'someValue' }
  }
}

This example demonstrates customizing the AJAX request with a POST method, including data, and a custom header.

Remember to consult the official Magnific Popup documentation for the latest options and best practices related to AJAX content loading. Pay particular attention to security considerations when handling user data in AJAX requests. Always validate and sanitize user inputs to prevent vulnerabilities.

Advanced Configuration

This section covers advanced techniques for customizing and extending Magnific Popup’s functionality.

Customizing the Popup Template

Magnific Popup’s default appearance can be extensively customized by modifying the HTML structure of the popup. This is achieved through the various markup options available for different popup types (image, inline, ajax, iframe). These options allow you to replace the default HTML with your own custom template.

For example, to modify the image popup’s markup:

$(document).ready(function() {
  $('.image-popup').magnificPopup({
    type: 'image',
    image: {
      markup: '<div class="mfp-figure">'+
                '<div class="mfp-close"></div>'+
                '<img class="mfp-img" src="%url%" alt="" />'+
                '<div class="mfp-bottom-bar">'+
                  '<div class="mfp-title"></div>'+
                  '<div class="mfp-counter"></div>'+
                '</div>'+
              '</div>'
    }
  });
});

This replaces the default image popup HTML with a custom structure. Note how %url% is used as a placeholder; Magnific Popup automatically replaces this with the actual image URL. You can similarly customize the markup for other popup types (inline, ajax, iframe) using their respective markup options. This allows complete control over the visual layout and elements within the popup. Remember to adjust CSS accordingly to style your custom markup.

Extending Magnific Popup

For significantly altering the core functionality, you can extend Magnific Popup by adding custom methods and options. This would typically involve creating a new plugin that interacts with the existing Magnific Popup functionality. This involves a more advanced understanding of JavaScript plugin development and how Magnific Popup’s internal structure works.

This is beyond the scope of a basic manual, but the source code and comments within Magnific Popup’s JavaScript file can provide guidance on how to create custom extensions and build on its capabilities.

Using Callbacks

Magnific Popup provides various callbacks (functions triggered at specific points during the popup lifecycle) that you can use to customize behavior at different stages. These callbacks are crucial for integrating Magnific Popup with your application’s logic. For example, the beforeOpen and afterClose callbacks are very common for performing operations just before or after a popup opens or closes. You can also use other callbacks such as beforeClose, open, close, etc., for tasks like updating content, validating user input or performing clean-up operations.

$('.my-popup').magnificPopup({
  type: 'image',
  beforeOpen: function() {
    console.log('Popup is about to open');
    // Add your code here
  },
  afterClose: function() {
    console.log('Popup has closed');
    // Add your code here
  }
});

Accessibility Considerations

To ensure your Magnific Popup implementation is accessible, follow these guidelines:

By following these guidelines, you can create more inclusive and user-friendly popup experiences. Remember that accessibility is an ongoing process; regularly review and test your implementation to ensure it remains compliant with accessibility standards.

Remember to consult the official Magnific Popup documentation for the most up-to-date information and detailed explanations of options and callbacks.

Responsive Design

Magnific Popup is designed to work responsively across various screen sizes and devices. However, some additional considerations and configurations are beneficial for optimal performance and user experience.

Adapting to Different Screen Sizes

Magnific Popup automatically adapts its layout to different screen sizes to a certain extent. However, you might need to adjust CSS rules to fine-tune its behavior for specific breakpoints. Use CSS media queries to target different screen sizes and apply appropriate styles. This ensures that elements within the popup (buttons, titles, images) are correctly sized and positioned across various devices. For instance:

/* Example CSS for responsive adjustments */
.mfp-container {
  max-width: 90%; /* Adjust the max-width as needed */
}

@media (max-width: 768px) {
  .mfp-container {
    max-width: 95%; /* Adjust for smaller screens */
  }
  .mfp-close {
    font-size: 20px; /* Adjust button size */
  }
}

This code adjusts the maximum width of the popup container and the close button size based on screen width. You will want to thoroughly test your implementation on various screen sizes and devices to ensure that it adapts appropriately.

Responsive Images

For responsive images within the popup, use the <img> tag’s srcset attribute or responsive image techniques (like picture element). This allows the browser to automatically select the most appropriate image size for the device’s screen resolution and pixel density.

<img src="image-small.jpg" srcset="image-medium.jpg 768w, image-large.jpg 1200w" alt="Responsive Image">

This provides small, medium, and large versions of the image. The browser will choose the most suitable image based on the screen’s capabilities, providing a better visual experience and faster loading times. For even more control, the picture element allows for more sophisticated responsive image handling.

Mobile Optimization

Consider the following for mobile optimization:

By addressing these points, you can create a Magnific Popup experience that is smooth, responsive, and enjoyable on all devices. Remember that thorough testing on various mobile devices and browsers is essential to identify and address any responsiveness issues.

Troubleshooting

This section addresses common issues and provides debugging tips for Magnific Popup.

Common Issues and Solutions

Debugging Tips

Browser Compatibility

Magnific Popup generally supports modern browsers. However, very old or outdated browsers might have limited or no support. The official documentation usually lists the officially supported browsers. Thorough testing across different browsers and versions is always recommended.

Known Limitations

If you encounter issues not covered here, consult the official Magnific Popup documentation, search for solutions on community forums, or submit a detailed issue report to the project maintainers, providing a minimal reproducible example to help them assist you effectively.

Examples and Use Cases

This section provides examples and use cases demonstrating Magnific Popup’s versatility.

Simple Image Popup

The simplest use case involves displaying a single image in a popup.

<a href="image.jpg" class="image-popup">
  <img src="thumbnail.jpg" alt="Image Thumbnail">
</a>
$(document).ready(function() {
  $('.image-popup').magnificPopup({
    type: 'image'
  });
});

This code creates an image popup. Clicking the <a> tag opens the larger image (image.jpg) in a Magnific Popup.

Building on the basic gallery example, a more complex gallery might incorporate custom thumbnails and navigation. While Magnific Popup doesn’t directly handle thumbnail generation, you can easily integrate this using other JavaScript libraries or custom JavaScript.

<div class="gallery-container">
  <a href="image1.jpg" class="gallery-item">
    <img src="thumb1.jpg" alt="Image 1 Thumbnail">
  </a>
  <a href="image2.jpg" class="gallery-item">
    <img src="thumb2.jpg" alt="Image 2 Thumbnail">
  </a>
  <a href="image3.jpg" class="gallery-item">
    <img src="thumb3.jpg" alt="Image 3 Thumbnail">
  </a>
</div>
$(document).ready(function() {
  $('.gallery-container').magnificPopup({
    delegate: 'a.gallery-item',
    type: 'image',
    gallery: {
      enabled: true
    },
    // Add custom options here for navigation, captions, etc.
  });
});

Here, clicking on any thumbnail within the .gallery-container opens the corresponding full-size image in a gallery. Additional options can be added for more customized behavior (e.g., captions, custom navigation controls). You’d likely add custom JavaScript to handle the thumbnail display and potentially other gallery enhancements beyond the basic functionality provided by Magnific Popup.

Integration with Other Libraries

Magnific Popup integrates well with other JavaScript libraries. For example, you could use a library for lazy loading images to improve performance, or a library for image caption generation. These integrations extend Magnific Popup’s capabilities significantly.

Custom Popup Designs

Using CSS, you can completely customize the look and feel of the popup. You can also use the markup option (as explained in the “Advanced Configuration” section) to drastically alter the HTML structure, creating unique popup designs tailored to your specific needs. This allows you to create highly themed and stylized popups consistent with your website’s branding and design.

Remember to consult the official Magnific Popup documentation and examples for more advanced scenarios and integrations. The examples provided here are basic starting points that can be expanded upon significantly. By combining these techniques and understanding Magnific Popup’s options and callbacks, you can create highly customized and functional popup experiences tailored to your specific project requirements.