https://github.com/hunyadi/boxsharp

A responsive lightbox pop-up window
https://github.com/hunyadi/boxsharp

javascript-vanilla lightbox web-components

Last synced: 19 days ago
JSON representation

A responsive lightbox pop-up window

Host: GitHub
URL: https://github.com/hunyadi/boxsharp
Owner: hunyadi
License: mit
Created: 2025-09-20T20:08:00.000Z (9 months ago)
Default Branch: master
Last Pushed: 2025-09-26T23:14:32.000Z (8 months ago)
Last Synced: 2025-09-27T01:21:20.292Z (8 months ago)
Topics: javascript-vanilla, lightbox, web-components
Language: JavaScript
Homepage: https://hunyadi.info.hu/projects/boxsharp/
Size: 40 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# boxsharp: a responsive lightbox pop-up window

[Demo page](https://hunyadi.info.hu/projects/boxsharp/) | [Project page](https://github.com/hunyadi/boxsharp/)

## Features

- **Modern browser support.** Works seamlessly in Chrome, Edge, Firefox, and Safari.
- **Versatile content display.** Handles images, videos, PDFs, same-page content and external pages.
- **Custom captions.** Add description to each item using plain text or HTML tags.
- **Flexible navigation.** Navigate using buttons, keyboard (left/right arrows), mouse, or swipe gestures.
- **History-aware.** Supports browser *back* and *forward* buttons to close and reopen.
- **Interactive image handling.** Expand large images and pan by dragging.
- **Optimized image loading.** Automatically selects the smallest image that fills the viewport.
- **Responsive design.** Oversized content is scaled down to fit the browser window.
- **Easy integration.** Includes a simple API and ready-to-use code snippets for fast setup.
- **Lightweight.** ~7 KB when gzipped.
- **No dependencies.** Built with 100% CSS and pure JavaScript (ES2020, Web Components).

## Setup

For a production deployment, add the following to the `` section of your HTML page:

```html

```

This contains both JavaScript code and CSS stylesheets combined into a single minified file.

For debug mode, use the following declaration instead:

```html

```

This contains the JavaScript code only, which loads `boxsharp.css` from the same directory where the code file is located.

## Syntax

boxsharp is implemented as a [web component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). When a `` element is added to the HTML DOM, its attributes and child elements are analyzed to determine how the image, video or other resource appears when the user clicks the element to open the pop-up window.

The following information sources are inspected for images:

* `href` attribute of ``. If `href` points to an image file, this file is added as a source.
* `srcset` attribute. `srcset` should use the width descriptor, not the pixel density descriptor.
* `` elements that are direct children of ``. Attributes `srcset`, `type` and `media` are extracted.
* `srcset` and `src` attributes of a descendant `` element. This is provided as a convenience feature to enlarge an image already shown on the page.

```html

...
TEXT

```

The following information is extracted for a video:

* `href` attribute of ``. If `href` points to a video file, this file is added as a source.
* `` elements that are direct children of ``. Attributes `src`, `type` and `media` are extracted.
* `` elements in a descendant `` element. Attributes `src`, `type` and `media` of any `` child elements of `` are extracted. This is a convenience feature to play a video in larger size.
* `src` attribute `src` of a descendant `` element.

```html

...

...

```

Captions for items are extracted from the following sources in the listed order:

* Elements assigned to the slot `caption`. This permits arbitrary HTML. Content of elements assigned to the slot `caption` is concatenated.
* `` in an encapsulated `` element. You can put arbitrary HTML in ``.
* `` in an encapsulating `` element. This lets us use `` in a `` element and read the caption text from the sibling element ``.
* `title` attribute

```html

TEXT
HTML

HTML

...

```

Some target items don't have an intrinsic size, e.g. when the pop-up window displays a web page from another site. In this case, you should explicitly set attributes `width` and `height` on ``.

```html
HTML
```

You can group related items into a collection using the `group` attribute. Visitors to the site are able to navigate between items that are assigned the same identifier without closing the pop-up window using keys *left* and *right* or swipe gestures. Related `` elements can be defined anywhere in the DOM, they don't have to be sibling elements.

```html
HTML
HTML...
```

When the `href` attribute of `` points to an element in the same document (i.e. uses a URL fragment that holds an element `id`), the element and all its descendants are copied to the pop-up window content display slot. If the source element has the inline style `display: none`, it is automatically removed when the content is cloned. This allows content to remain hidden in the document until it is about to be shown in the pop-up window.

```html
HTML
```

## Classic syntax

For legacy use cases, a classic syntax is available that relies on attributes of the anchor element `` as opposed to ``. You need to invoke the `scan` static method to analyze the attributes of an `` element:

```javascript
import { BoxsharpCollection } from "./boxsharp/boxsharp.min.js";
document.addEventListener("DOMContentLoaded", () => {
BoxsharpCollection.scan("boxsharp");
});
```

Once you call `scan`, the code inspects attributes `href`, `rel`, `data-srcset` and `title`, and looks for an `` element wrapped in `` for attributes `src`, `srcset` and `alt`. In the classic syntax, `rel` distinguishes normal links from boxsharp links:

* Anchors with a `rel` of `NAME` open a pop-up window when clicked, showing the resource referenced in `href`. `NAME` defaults to `boxsharp` (see above) but you can use any name you prefer.
* Anchors with a `rel` of `NAME-*` form a collection (gallery) in which the user is able to navigate between the items without closing the pop-up window. `*` means any sequence of characters. You have to use the same `rel` attribute for items in the same collection.

Captions are extracted from the same sources as with the modern syntax. However, anchor elements cannot nest in HTML, which prevents using links in `` when the entire `` element is wrapped in the defining `` element. We recommend that you place the `` element inside ``.

## Customizing appearance

Pop-up window caption and same-page content (passed with `href` pointing to an HTML `id`) are adopted via the web component slotting mechanism. This means that CSS styles applied in the host document are inherited.

Assume we set a pop-up window caption using the attribute `slot`:

```html

...

This example demonstrates how to apply CSS.

```

The optional attribute `hidden` ensures that the text remains invisible unless displayed in the pop-up window.

We can then make the text of the HTML element `` go green when the caption appears under the image/video if we apply the following CSS in the host document: