svelte-lightbox

Lightweight lightbox library for Svelte

!workflow status
!version
!bundle size
!MIT
!issues count
!downloads

Lightweight Lightbox, but very customizable Svelte component library. There is also support for
mobile devices. Note that this first version of this library, if you notice any bug,
please report it to this library's GitHub repository to the 'Issues' section.

Instalation

> ``bash
> npm i svelte-lightbox -D
> `

How to use

1. Make Svelte page

$3

2. Include import { Lightbox } from 'svelte-lightbox'; into that file.

3. Make component and image you need to display put inside slot (as its child).

$3

2. Include import { LightboxGallery, GalleryImage, GalleryThumbnail } from 'svelte-lightbox'; into that file.

3. Make component and append to it list of , which each contains
desired image (or it could be video).

4. Prepend with element or svelte:fragment with prop slot equal to "thumbnail", under this element
place your thumbnail layout, which is basically layout with images wrapped inside .

$3

`html



description="Simple lightbox">



`

If you need more usage examples, you should see demo page code at this library GitHub repository.

API

This library mainly consists out of 2 components which are and , but their customization
is significant part of using them.

This component is meant to be used to display image, which is clickable, that click will trigger action to open same or
different image in larger scale.

$3

Image's title that is displayed below the image (in a lightbox), feel free to use HTML (eg,
, ). Everything
in a lightbox footer is aligned to the left, but you can override it by putting it into which would allow you to
apply a different style or a class of your choosing.

$3

Image's description that is, similarly to the title, displayed under the image (in a lightbox). The difference between
those two are the title is wrapped in

and description is wrapped in

.

$3

Select between these 3 presets:

- '' - Default preset, doesn't make any drastic behavior changes, just displays image in its maximum size and fits into viewport.

- 'fullscreen' - Makes image fullscreen to cover at least one of axes.

- 'scroll' - Enables scrolling big image instead of making it smaller to fit into the screen.




$3

#### Using LightboxCustomization object

Customization object contains these props, which represent html props of their key (e.g. closeButtonProps = html props of
close button of).

- closeButtonProps: HTMLButtonElement
- lightboxFooterProps: HTMLDivElement
- lightboxHeaderProps: HTMLDivElement
- coverProps: HTMLDivElement
- lightboxProps: HTMLDivElement
- thumbnailProps: HTMLDivElement

#### Using CSS

If you'd like to change global styles, feel free to override these global CSS classes instead: .svelte-lightbox-main,
.svelte-lightbox-body, .svelte-lightbox-overlay, .svelte-lightbox-header, .svelte-lightbox-footer and .svelte-lightbox-thumbnail.

$3

Duration of lightbox toggle, in milliseconds. Based on this number are calculated transitions for lightbox cover. Default
300.



$3

Keeps body scroll while lightbox is open. Default false.

$3

Enables image inside lightbox to resize above its resolution. Default false.

$3

Enables inferring thumbnail from lightbox content, if thumbnail isn't specified. Default true.

$3

Enables closing lightbox on keydown which is equal to escape button. Default true.

$3

Anywhere user clicks when modal is opened, closes it. Default false.

$3

Shows close button. Default true.

$3

Allows you to programmatically control lightbox visibility without programmaticController. Default varies on user activity.

$3

Object with these basic control functions:

- toggle () => void - toggles lightbox (opened -> closed, vice versa)
- open () => void - opens lightbox
- close () => void - closes lightbox

---

Lightbox component with explicitly defined thumbnail layout and multiple images, allows listing thorough all images within
gallery. According to almost 2 years experience of using this component (in early versions), I found out, that gallery without
thumbnail layout doesn't give any sense in most of the cases, so I decided to embed this feature in design of this component.

$3

Same as in title, but this is same in whole gallery. can override this title for specific image.

$3

Same as in description, but this is same in whole gallery. can override this description for
specific image.

$3

Same as in .

$3

Same as in .

$3

Same as in .

$3

Same as in .

$3

Same as in .

$3

Same as in .

$3

Same as in .

$3

Same as in .

$3

Same as in .

$3

Number which sets visibility of image with id equal to it. Also optional, this is used for programmatic selecting of
visible image when Lightbox is opened.

$3

Allows customizing gallery arrows.

#### color string

Sets arrow color, valid value is any valid css color.

#### character GalleryArrowCharacter (string)

Sets arrow charter in edge cases (0th and last item of gallery). Valid values:

- '' - Leaves arrow inactive and disables particular arrow on keyboard in edge case.

- 'hide' - Hides arrow and disables particular arrow on keyboard in edge case.

- 'loop' - Arrows are always active and keyboard arrows as well. For instance when user clicks left arrow on first image, last image
will be displayed.

#### enableKeyboardControl boolean

Enables navigation in gallery using keyboard arrows. Default true.

$3

Object with these basic control functions:

- toggle () => void - toggles lightbox (opened -> closed, vice versa)
- open () => void - opens lightbox
- openImage (imageId: number) => void - opens lightbox at specific image
- close () => void - closes lightbox

---

#### id number

Link to gallery image, it can be set to any number within gallery images, starting with 0. Default is order of
, so let's say you have 3 thumbnails under , the first thumbnails has id 0, next one
1 and third 2.

---

$3

Same as title, but this is image specific, that means, it will be only shown for particular image.

$3

Same as description, but this is image specific, that means, it will be only shown for particular image.

---

Custom lightbox

This library by design allows you to construct custom lightbox by providing you with basic building block of lightbox.
If you want to use this advanced functionality, you are supposed to read code (I recommend reading it from GitHub, code
from NPM is already processed) of basic building blocks and examples of their usage (, )
as well, this documentation is only brief overview. You can take available building blocks and lay them down in different
way, or replace some of them by your own tweaked variants. Basic building blocks are:

$3

####

Name says it all.

####

Makes content of slot direct child of , this can be especially useful when using CSS frameworks, which can break
z-index effect in some cases (element with higher index is lower than element with lower index).

####

Cover behind lightbox modal, dimmed background.

####

Name says it all.

####

Header of lightbox modal, contains close button as well as window keypress binding.

####

Body of lightbox modal, contains lightbox image.

####

Footer of lightbox modal, contains title, description of image and gallery counter.

####

Layout with image space, left and right arrow, internal logic of gallery.

#### and

Buttons which allow you to move within gallery.

---

i18n

There is 1 thing that has to be localized and that is gallery counter, that what shows user where in gallery is located
(e.g. Image 2 of 4). Gallery counter text can be customized by overriding its generator. That can be done by importing
i18n from 'svelte-lightbox' and then setting generateLocalizedGalleryCounter to desired generator.

$3

`ts
(activeImage: number, imageCount: number): string => {
return Image ${activeImage + 1} of ${imageCount}
}
``

Contribution

Every issue or code contribution is welcome.

License

It's free, this component is under MIT license.