bigger-picture-fork
v1.1.25
Published
Javascript photo / video / iframe / html lightbox gallery
Downloads
15
Maintainers
Readme
Bigger Picture
Pretty good JavaScript lightbox gallery with a small footprint. Demo: https://biggerpicture.henrygd.me
https://user-images.githubusercontent.com/8519632/165216178-bd9a0b03-6ee5-42fd-b303-f92d281eb494.mp4
Features
- High Performance - Smooth even with huge images, especially if using srcset.
- Lightweight - Less than half the size of lightGallery or PhotoSwipe (the king - not bashing it).
- Zoomable - Click, wheel, or pinch to zoom photos up to native resolution.
- Responsive images - Pass in a srcset value and Bigger Picture will handle the rest.
- Video, audio, iframe, and html support - No need for multiple libraries, plugins, or hacky workarounds.
- Inline galleries and custom layouts - Bigger Picture can be mounted anywhere and has an easy-to-use API.
- Accessible - Supports alt text, image / video captions, custom HTML attributes, keyboard navigation, respects prefers-reduced-motion, and manages focus.
- Free software - MIT licensed. Do whatever you want with it, just don't be an asshole please.
Install
npm install bigger-picture
Add the required CSS or SCSS to your project. You can import "bigger-picture/css"
to avoid manually replacing styles when you update.
Alternatively, you can load from a CDN like jsDelivr.
Usage
This is a very basic example using HTML to supply data. You don't need to initialize more than once unless you want multiple galleries with different targets.
For passing data via object, see Passing Item Data via Object.
Using Svelte? You can save a few bytes in your bundle. See Usage with Svelte.
import BiggerPicture from 'bigger-picture'
// initialize
let bp = BiggerPicture({
target: document.body,
})
// open (will be a child of the target element above)
bp.open({
items: document.querySelectorAll('#images a'),
})
<div id="images">
<a
href="example.jpg"
data-img="example.jpg"
data-thumb="example_thumb.jpg"
data-alt="Example"
data-height="2500"
data-width="1667"
>
<img src="example_thumb.jpg" alt="Example" />
</a>
</div>
Methods
open(options)
Opens the lightbox.
close
Closes the lightbox.
next
Changes to next item in gallery.
prev
Changes to previous item in gallery.
setPosition(position)
Changes to position
item in gallery (zero-indexed).
Options
items
Type: NodeList
or Node
or Array
The data source for the displayed items. See Item Properties for details.
If using NodeList or Node, the information is passed via data attributes. If using Array, the information is passed via object.
el
Type: Node
Default: undefined
If the specified node matches a node in items
(or matches the element
value on an item if using an array), the gallery will start at that position. For example, you could use this inside a click handler by passing event.target
. (See codesandbox demo for example.)
position
Type: number
Default: 0
Start position of gallery. If using el
this will be ignored.
Note: This number is zero-indexed. The third item would be position 2.
scale
Type: number
Default: 0.99
Controls the size of the displayed item. Use 1
to fill item to screen edges.
intro
Type: string
Default: undefined
Overrides the default intro animation. Currently fadeup
is the only alternative.
inline
Type: boolean
Default: false
Specifies that the lightbox is inline. Interaction events are modified to avoid hijacking scroll and tab press.
Note: The container element for an inline gallery should be set to position: relative
noClose
Type: boolean
Default: false
Hides the close button and prevents the lightbox from closing unless the close
method is called. Recommended to use in combination with an inline gallery.
noPinch
Type: function
Return a truthy value to disable pinch zoom. Function is executed at the time of the pinch. Supplies container
- the gallery's wrapper element.
bp.open({
noPinch: (container) => container.clientWidth < 800,
})
focusWrap
Type: node
Specify wrapper element to trap focus within on tab press. Useful when mounting a gallery inside a custom layout.
maxZoom
Type: number
Default: 10
Restricts an image's maximum zoom to maxZoom
times the starting size, even if the item's width
/ height
is larger. For example, a maxZoom
of 2 on an image that starts at 800px width would limit the image to a maximum zoom of 1600px width. A maxZoom
of 1 would prevent zooming entirely.
Note: If
maxZoom
is set on an individual item it will override the value set in options.
onOpen
Type: function
Executes just before intro animation. Supplies container
- the gallery's wrapper element, and activeItem
- an object containing the currently displayed item's data.
bp.open({
onOpen: (container) => container.classList.add('custom-class'),
})
onUpdate
Type: function
Executes just after the active item is updated. Supplies container
and activeItem
.
bp.open({
onUpdate(container, activeItem) {
console.log('container', container)
console.log('activeItem', activeItem)
},
})
onClose
Type: function
Executes just before outro animation. Supplies container
and activeItem
.
onClosed
Type: function
Executes just after the lightbox has been closed and removed from the page.
onResize
Type: function
Executes when the dimensions of the gallery (not the window) are changed. Supplies container
and activeItem
.
onImageClick
Type: function
Executes when an image is clicked. Return a truthy value to prevent zooming. Supplies container
and activeItem
.
This method was added to make it easier to open a full screen instance when an image is clicked within an inline gallery (example CodeSandbox), but could be used for other purposes.
onError
Type: function
Executes if an error is thrown when loading an image, audio, or video item. Supplies container
, activeItem
and error
.
Item Properties
width
Type: number
or string
Default: 1920
Largest possible width of media item in pixels. Not required for HTML, which can be sized via CSS.
height
Type: number
or string
Default: 1080
Largest possible height of media item in pixels. Not required for HTML, which can be sized via CSS.
thumb
Type: string
URL or path to image used for thumbnail displayed before media loads.
img
Type: string
URL or path to full image. Can be a srcset
value.
When using srcset
, the sizes
value will update automatically when an image is zoomed. You may override this behavior by setting the sizes
value.
iframe
Type: string
URL or path to iframe source
sources
Type: Array
or string
For native video and audio, an array of objects specifying src
(required) and type
(optional). A string may be used if it is JSON parsable. Each object will create a source
element, and all key / value pairs in the object will be added as attributes.
<div data-sources='[{"src": "example.webm", "type": "video/webm"}, {"src": "example.mp4", "type": "video/mp4"}]'>
html
Type: string
HTML that will be rendered in the container. When using HTML, please control dimensions with CSS. No need to pass width
or height
.
For advanced use, you can pass an empty string, then mount a component using the onOpen
method:
// mounting svelte component (firewatch example from demo site)
onOpen(container) {
new Firewatch({
target: container.querySelector('.bp-html'),
})
},
attr
Type: object
or string
Add or override default attributes on the <img>
, <iframe>
, <video>
, or <audio>
elements.
<div data-attr='{"credentialless": true, "referrerpolicy": "no-referrer"}'>
alt
Type: string
Image alternative text
title
Type: string
Title attribute for iframes
caption
Type: string
Text to be displayed using built in caption. You may pass html tags and styles can be overriden via CSS.
sizes
Type: string
Sets the sizes attribute if you're using srcset
.
maxZoom
Type: number
Default: 10
Restricts an image's maximum zoom to maxZoom
times the starting size, even if the item's width
/ height
is larger. For example, a maxZoom
of 2 on an image that starts at 800px width would limit the image to a maximum zoom of 1600px width. A maxZoom
of 1 would prevent zooming entirely.
Note: If
maxZoom
is set on an individual item it will override the value set in options. Attribute name isdata-max-zoom
.
tracks
Type: string
or Array
Array of text track data to use with videos. String option is just a stringified array.
Below is an example for passing English and Spanish captions. See the MDN page on track elements for more information.
<div data-tracks='[{"label": "English", "kind": "captions", "srclang": "en", "src": "en.vtt", "default": "true"}, {"label": "Español", "kind": "captions", "srclang": "es", "src": "es.vtt"}]'></div>
Passing Item Data via Object
To control the default open / close animation, also add a property element
to each item that contains a node on the page. The active item's element
will be where the animation opens from / closes to. If you're not using the default scale animation, this is not needed.
bp.open({
items: [
{
img: 'example.jpg',
thumb: 'example_thumb.jpg',
alt: 'Example',
height: 2500,
width: 1667,
// if you're using the default intro animation
element: node,
},
],
})
Usage with Svelte
Use the source .svelte
files directly by importing bigger-picture/svelte
. This will decrease the size of the library by 20 to 30 percent in most cases.
import BiggerPicture from 'bigger-picture/svelte'
License
MIT