Skip to content

Latest commit

 

History

History
321 lines (244 loc) · 8.55 KB

README.md

File metadata and controls

321 lines (244 loc) · 8.55 KB
Raw

logo BigPicture npm File Size

Example page screenshot Vanilla JavaScript image / video viewer meant to be as lightweight and easy to use as possible.

Check out the example page here

Installation

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.

Usage

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.

Options

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.opts

Sources

Remote video file

BigPicture({
	el: e.target,
	vidSrc: 'https://yourvideo.mp4',
	// or with multiple sources
	// vidSrc: ['https://yourvideo.mp4', 'https://yourvideo.webm']
})

Youtube

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',
})

Vimeo

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',
})

iframe embed

Pass in the URL from the iframe.

BigPicture({
	el: e.target,
	iframeSrc: 'https://youriframe.html',
})

Audio

BigPicture({
	el: e.target,
	audio: 'https://youraudio.mp3',
})

Remote individual image

BigPicture({
	el: e.target,
	imgSrc: 'https://yourimage.jpg',
})

Galleries

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,
})

Captions

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." />

Optional callbacks

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)
	},
})

Hide default loading icon

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,
})

Change dimensions of embed / youtube / vimeo

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()

Error handling

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')
	},
})

Troubleshooting

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.