Install via package manager or add a script from the dist directory to your page. CDN links are available via jsDelivr.
npm install bigpicture
// import
import BigPicture from 'bigpicture'
// or require
var BigPicture = require('bigpicture')Or with a script tag:
<script src="BigPicture.js"></script>No additional CSS file is neccesary.
When you want to open something, pass an object to BigPicture containing the element from which you want the animation to start, and other optional parameters depending on what you want to do. Examples below use e.target to refer to the trigger element being interacted with in the context of an event handler. You can use a different element if you want (for example, different buttons could be set up to open videos from the same central showcase element).
If your trigger element is an image or an element with a background image, you can open it directly by passing only el.
BigPicture({
// element from which animation starts (required)
el: e.target,
// image url
imgSrc: 'https://yourimage.jpg',
// video src (String) or sources (Array)
vidSrc: ['https://yourvideo.mp4', 'https://yourvideo.webm'],
// iframe embed URL
iframeSrc: 'https://youriframe.html',
// vimeo ID
vimeoSrc: '119287310',
// youtube ID
ytSrc: 'z_PeaHVcohg',
// use youtube-nocookie
ytNoCookie: false,
// audio URL
audio: 'https://youraudio.mp3',
// see below for more gallery options
gallery: '#image_container',
// attribute used to find gallery elements
galleryAttribute: 'data-bp',
// set custom dimensions for embeds / videos
dimensions: [1920, 1080],
// show or hide default loading indicator
noLoader: false,
// customize the overlay color (any valid css color value)
overlayColor: 'rgba(0, 0, 0, .8)',
// open animation callback
animationStart: () => {},
// open animation callback
animationEnd: () => {},
// close callback
onClose: () => {},
// gallery image change callback
onChangeImage: () => {},
})The function returns an object with a few helpful properties / methods.
var bp = BigPicture({...})
// close
bp.close()
// next gallery image
bp.next()
// previous gallery image
bp.prev()
// access to active display element (img, video, iframe wrapper div)
bp.display
// options of active instance
bp.optsBigPicture({
el: e.target,
vidSrc: 'https://yourvideo.mp4',
// or with multiple sources
// vidSrc: ['https://yourvideo.mp4', 'https://yourvideo.webm']
})Pass in the video ID from the url. For example, the ID for https://www.youtube.com/watch?v=z_PeaHVcohg would be z_PeaHVcohg (The v parameter in the address).
BigPicture({
el: e.target,
ytSrc: 'z_PeaHVcohg',
})Like Youtube, pass in the video ID from the url. The ID for https://vimeo.com/119287310 would be 119287310.
BigPicture({
el: e.target,
vimeoSrc: '119287310',
})Pass in the URL from the iframe.
BigPicture({
el: e.target,
iframeSrc: 'https://youriframe.html',
})BigPicture({
el: e.target,
audio: 'https://youraudio.mp3',
})BigPicture({
el: e.target,
imgSrc: 'https://yourimage.jpg',
})Add a data-bp attribute to your elements with the image you want to open, and pass a selector string or NodeList to the function. The string should specify a container which has data-bp elements somewhere inside, whereas the NodeList should be the elements themselves.
The attribute name can be overridden with the galleryAttribute option as of 2.4.0. For instance, galleryAttribute: 'src' would open the thumbs in the example below, and the data-bp attributes would be unnecessary.
<div id="image_container">
<img src="photo1_thumb.jpg" data-bp="photo1.jpg" class="example" />
<img src="photo2_thumb.jpg" data-bp="photo2.jpg" />
<img src="photo3_thumb.jpg" data-bp="photo3.jpg" class="example" />
</div>// opens gallery w/ all three images
BigPicture({
el: e.target,
gallery: '#image_container',
})// opens gallery w/ the two images matching the selector
BigPicture({
el: e.target,
gallery: document.querySelectorAll('#image_container .example'),
})Alternatively, you can pass in an array of objects. The gallery will go through these in order. Here's example code for the unsplash gallery on the demo site:
var unsplashImages = ['meiying', 'clemono2', 'heftiba'].map(function (user) {
return {
src: 'https://source.unsplash.com/user/' + user + '/daily',
// caption: 'This image is from unsplash'
}
})
BigPicture({
el: e.target,
gallery: unsplashImages,
// optionally specify a starting index
position: 2,
})You can also loop the gallery (next on last image gives you the first image, and vice versa).
BigPicture({
el: e.target,
gallery: '#image_container',
loop: true,
})To display a caption, add a data-caption attribute with the desired text or HTML to the trigger element itself.
<img src="yourimage.jpg" data-caption="Example of an optional caption." />animationStart and animationEnd run at the start or end of the opening animation. animationStart will run even if there's an error, so it's okay to use if you want to hide your own custom loader.
onClose runs after closing animation finishes.
onChangeImage runs when a gallery image is changed and provides useful data about the current image.
// example of how scrolling can be disabled using henrygd.me/hide-show-scroll
BigPicture({
el: e.target,
// animationStart executed immediately before open animation starts
animationStart: hideScroll,
// animationEnd executed immediately after open animation finishes
animationEnd: function () {
console.log('it has opened')
},
// onClose executed immediately after close animation finishes
onClose: showScroll,
// onChangeImage executed on gallery image change
onChangeImage: function (props) {
console.log('gallery image changed', props)
},
})If you're loading remote images or videos and don't want the default loading icon displayed, set noLoader to true.
BigPicture({
el: e.target,
vimeoSrc: '119287310',
noLoader: true,
})By default, embeds are displayed in 16:9 aspect at a maximum of 1920px by 1080px. To change this, supply an array with width and height in pixels. Default is [1920, 1080].
BigPicture({
el: e.target,
ytSrc: 'X2lkvrMa27c',
dimensions: [1226, 900],
})Dimensions can also be updated on the fly.
var bp = BigPicture({...})
bp.opts.dimensions = [500, 500]
bp.updateDimensions()You may override the default error alert for images, audio, and direct video links by passing an onError function.
BigPicture({
el: e.target,
onError: function () {
console.log('there was an error')
},
})If the media or loading icon fails to display, it's probably a z-index issue. The media container has a default z-index of 9999, and the loading icon has a z-index of 9 relative to the trigger element's parent container.
License: MIT
All images found on Unsplash
Towers of Pfeiffer video by Grant Porter (CC-BY)
Music by Nordgroove via icons8
📢 Note: I made another lightbox library with features like responsive images, zooming, HTML modals, and various improvements over this one. Please check out the Bigger Picture demo site or GitHub repository.