Skip to content
Get packs

Guide · Open source

How to use Magnific Popup: install, setup and alternatives

Updated · written with AI from the project's own documentation and checked against our catalogue data

Magnific Popup is a small, responsive lightbox plugin that shows images, galleries and other content in a popup overlay. It is written for jQuery or Zepto.js. This guide explains how to install it, where its files live, how to build it yourself, and when you should choose something else, since the author's README now marks the plugin as deprecated.

Magnific Popupdimsemenov/Magnific-Popup · ★ 11.3k · MIT

Quick start

  1. 1Confirm the fit. Check that your site uses jQuery or Zepto.js and that a deprecated plugin is acceptable for your project.
  2. 2Install the package. Run npm install magnific-popup or bower install magnific-popup in your project folder.
  3. 3Locate the files. Find the generated JS and CSS in the dist/ folder of the package or repository.
  4. 4Read the documentation. Follow the getting started guide and API on the documentation page linked from the README.
  5. 5Build from source if needed. Clone the repository, run npm install, then run grunt, or grunt nosite if you do not want Jekyll.
  6. 6Plan an alternative for new work. For new projects, evaluate the native dialog element or PhotoSwipe, as the README recommends.

Check whether Magnific Popup fits your project

Read this before installing anything. The README states that the plugin is deprecated and that only critical or security bug fixes will be released. It recommends the native <dialog> element for a basic popup or modal, and the author's PhotoSwipe library for an advanced image gallery.

Magnific Popup is a good fit mainly for maintaining an existing site that already uses it with jQuery, or for a jQuery or Zepto.js project that needs a small, responsive popup with a documented API.

  • Existing jQuery or Zepto.js site: keep using it and watch for security fixes.
  • New project: consider the native <dialog> element or PhotoSwipe instead.
  • Projects without jQuery or Zepto.js: the README describes the plugin only for those libraries.

Install Magnific Popup with npm or Bower

The README lists two optional package-manager installs. Your project needs jQuery or Zepto.js available, because the plugin is built for them.

Run one of the following from your project folder.

  • npm: npm install magnific-popup
  • Bower: bower install magnific-popup
npm install magnific-popup

Find the generated JS and CSS files

The ready-to-use popup JavaScript and CSS are in the dist/ folder of the repository. The Sass stylesheet and JavaScript source parts are in src/, with the main stylesheet at src/css/main.scss. The examples and documentation site is in website/, and the documentation page itself is website/documentation.md.

The README also links an online build tool on the documentation page, which you can use instead of building locally.

  • dist/: generated popup JS and CSS
  • src/: Sass and JS source files
  • website/: examples and documentation
  • website/documentation.md: documentation page source

Build Magnific Popup from source

Build from source only if you need to change the plugin or generate the files yourself. The README says you need Node.js, Grunt.js, Ruby and Jekyll installed first. The steps are to clone the repository, install Node dependencies, then run grunt.

If you do not have or want Jekyll, the README says grunt nosite builds only the popup JS and CSS into dist/.

  • Run grunt watch to rebuild automatically when files in src/ or website/ change.
  • Run grunt nosite to build only the JS and CSS in dist/ without Jekyll.
git clone https://github.com/dimsemenov/Magnific-Popup.git cd Magnific-Popup && npm install grunt

Get help and report problems

The README asks you to report bugs through GitHub and to ask general questions on Stack Overflow under the magnific-popup tag. The author also says to email for assistance, and notes that changes are welcome as pull requests, including small documentation fixes.

Before you start a project, read the license section. The script is MIT licensed, but the author asks that nobody create a public WordPress plugin based on it without contacting him first.

  • Bugs: GitHub issues
  • General questions: Stack Overflow, tag magnific-popup
  • Contributions: GitHub pull requests

What people use it for

  • Maintaining an existing website that already uses Magnific Popup with jQuery
  • Adding a popup to a jQuery or Zepto.js project that needs a small responsive lightbox
  • Building a custom copy of the plugin from source with grunt
  • Using a CMS extension, such as the Drupal module or Contao extension listed in the README

Frequently asked questions

Is Magnific Popup still maintained?

The README says the plugin is deprecated and that only critical or security bug fixes will be released in future. It is not recommended for new projects.

Is Magnific Popup free to use?

The script is MIT licensed. The README says it is free and will always be kept that way, with one request: do not create a public WordPress plugin based on it without contacting the author first.

How do I install Magnific Popup?

Use npm install magnific-popup or bower install magnific-popup. The plugin needs jQuery or Zepto.js in your project.

Does Magnific Popup work without jQuery?

The README describes it as a plugin for jQuery and Zepto.js. Without one of those libraries, the README does not say it will work.

What should I use instead of Magnific Popup?

The README recommends the native dialog element for a basic popup or modal, and PhotoSwipe for an advanced image gallery. Comparable projects include fancyBox, Lightbox2 and GLightbox.

Where do I get help if something breaks?

Report bugs on GitHub and ask general questions on Stack Overflow using the magnific-popup tag. The author also says to email for assistance.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Magnific Popup suits teams that already run it on a jQuery or Zepto.js site and need a small, documented, MIT-licensed lightbox. For new projects, or for advanced galleries, the README points to the native dialog element or PhotoSwipe instead.

Install options & downloads