HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
LightboxView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA viewer that shows one item at a time over the page.StableSince 0.100.0MediaUsageimport'@fusion.dev/helix/lightbox'import'@fusion.dev/helix-headless/lightbox'Preview
API ReferenceRoothelix-lightboxA viewer that shows one item at a time over the page.
PropTypeDescriptionactivestringThe value of the current item.controlsbooleanDefaultfalseDraws the viewer's own previous, next and close controls over the picture,
and zoom-out and zoom-in controls where max-zoom allows zooming.counterbooleanDefaultfalseDraws the place of the shown item in the set over the picture, in the
words of status-label, such as "2 of 5". It hides with the controls while
the reader is idle. Screen readers hear the place from the live region, so
the drawn copy is hidden from them.defaultActivestringDefault""The value of the item declared current in markup.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.dismissLabelstringDefault"Close"The close control's accessible name. Translate it with the rest of your
interface.fallbackLabelstringDefault"Lightbox"The viewer's name where label is empty.idleDelaynumberDefault0How long the user can be idle before the header and footer hide, in
milliseconds. The attribute also takes a CSS time, such as 3s.labelstringDefault""The viewer's name, read by screen readers.loopbooleanDefaultfalseWhether moving past the last item returns to the first.maxZoomnumberDefault1How far a reader can zoom into the shown item, as a scale, such as 3.
1, the default, turns zooming off.nextLabelstringDefault"Next"The next control's accessible name.openbooleanWhether the element is open.previousLabelstringDefault"Previous"The previous control's accessible name.slideLabelstringDefault"{index} of {count}"The name of an item with no label of its own, with {index} and
{count} filled in, written in the locale.slideRoleLabelstringDefault"slide"The word screen readers announce in place of an item's role, set as
aria-roledescription. Translate it with the rest of your text, or empty
it to leave the role as group.statusLabelstringDefault"{index} of {count}"The status text that says which item is shown, with {index}, {count}
and the item's {label} filled in, the numbers written in the locale.zoomInLabelstringDefault"Zoom in"The zoom-in control's accessible name.zoomOutLabelstringDefault"Zoom out"The zoom-out control's accessible name.zoomStatusLabelstringDefault"Zoomed to {scale, number, percent}"What the live region says once a reader has stopped zooming. {scale, number, percent} writes the scale as a percentage the way the locale
writes one, such as 150%, or 150 % in French. {percent} is the same
scale as a whole number, for a sentence that places the sign itself. Empty
it to say nothing.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The items, which are <helix-headless-lightbox-item> elements.dismiss-iconReplaces the glyph inside the close control.footerContent below the item, such as a counter or a thumbnail strip.headerContent above the item, such as a title and a close button.next-iconReplaces the glyph inside the next control.previous-iconReplaces the glyph inside the previous control.zoom-in-iconReplaces the glyph inside the zoom-in control.zoom-out-iconReplaces the glyph inside the zoom-out control.
EventTypeDescriptioncloseEventFired when the viewer closes. The component dispatches it again from the host, because the dialog's own event does not leave the shadow root.helix-activateHelixActivateEventFired after the shown item changes, when the element already holds the new item.helix-before-activateHelixBeforeActivateEventFired before the shown item changes. Cancelable: cancel it to keep the current item. It is the only way to stop the change.helix-before-closeHelixBeforeCloseEventFired before the viewer closes. Cancelable.helix-before-openHelixBeforeOpenEventFired before the viewer opens. Cancelable.toggleToggleEventFired when the viewer opens or closes, with newState and oldState.
MethodTypeDescriptionclose() => voidCloses the viewer, unless a helix-before-close listener cancels it.next() => voidShows the next item. After the last item, it shows the first when loop
is set.previous() => voidShows the previous item. Before the first item, it shows the last when
loop is set.requestActive(next: string, cause: string) => booleanRequests a new current item, and returns whether the change was applied.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.show() => voidOpens the viewer, which makes the rest of the page inert.toggleFullscreen() => voidMakes the viewer fill the screen, or exits fullscreen.toggleOpen() => booleanRequests the opposite of the current state.zoomTo(scale: number) => voidZooms the shown item to scale, held between 1 and max-zoom, about
the middle of the viewport.
PartDescriptioncounterThe place of the shown item in the set, drawn with counter.dialogThe native dialog element.dismissThe close control, drawn with controls.dismiss-markThe glyph on the close control, where none is slotted.footerThe slot the footer is in. It draws no box until you give it one.headerThe slot the header is in. It draws no box until you give it one.liveThe live region that announces which item is shown, and the scale once a reader has zoomed. Visually hidden in the styled tier.nextThe control that shows the next item, drawn with controls.next-markThe glyph on the next control, where none is slotted.previousThe control that shows the previous item, drawn with controls.previous-markThe glyph on the previous control, where none is slotted.viewportThe box the current item is shown in.zoom-inThe control that zooms in by half again, drawn with controls where max-zoom allows zooming.zoom-in-markThe glyph on the zoom-in control, where none is slotted.zoom-outThe control that zooms back out, drawn with controls where max-zoom allows zooming.zoom-out-markThe glyph on the zoom-out control, where none is slotted.
CSS PropertyDescription--lightbox-control-sizeSize of the previous, next and close controls drawn with controls.--lightbox-foregroundColor of the controls and text drawn over the content.--lightbox-gapSpace between the header or footer and the content.--lightbox-paddingInset from the edges of the screen.--lightbox-pan-xHow far the zoomed item is moved across from the middle of the viewport, in pixels, toward the right. Written only while zoomed.--lightbox-pan-yHow far the zoomed item is moved down from the middle of the viewport, in pixels. Written only while zoomed.--lightbox-scrimThe overlay color on the page behind the viewer. Set it on the host, because a var() inside ::backdrop cannot resolve a token.--lightbox-zoomThe scale the shown item is zoomed to, such as 2. Written only while zoomed.
Custom stateDescriptionenteringFrom the moment the viewer opens until its entrance has finished.exitingFrom the moment the viewer closes until its exit has finished.fullscreenWhile the viewer fills the screen.idleThe user has been still long enough for the controls to hide.openWhile the viewer is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.zoomableWhile max-zoom lets a reader zoom.zoomedWhile the shown item is zoomed past its own size.
Itemhelix-lightbox-itemOne item a lightbox can show, such as a picture, a video frame, or a chart.
PropTypeDescriptioncurrentbooleanDefaultfalseWhether this item is the one shown.labelstringDefault""The item's name. It names the item's group, and fills {label} in the
lightbox's status-label.valuestringDefault""The item's identifier. The root compares its active value against it.
Without one, the item is named by its place in the set, counted from 1.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The content to show.descriptionA line under the content that describes it.
PartDescriptionitemThe box the content is shown in.
CSS PropertyDescription--lightbox-item-description-colorColor of the line under the content.--lightbox-item-gapSpace between the content and the line under it.
Custom stateDescriptioncurrentThe item the lightbox is showing.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-lightboxA viewer that shows one item at a time over the page.
PropTypeDescriptionactivestringThe value of the current item.controlsbooleanDefaultfalseDraws the viewer's own previous, next and close controls over the picture,
and zoom-out and zoom-in controls where max-zoom allows zooming.counterbooleanDefaultfalseDraws the place of the shown item in the set over the picture, in the
words of status-label, such as "2 of 5". It hides with the controls while
the reader is idle. Screen readers hear the place from the live region, so
the drawn copy is hidden from them.defaultActivestringDefault""The value of the item declared current in markup.defaultOpenbooleanDefaultfalseWhether the element starts open. Ignored once open is written.dismissLabelstringDefault"Close"The close control's accessible name. Translate it with the rest of your
interface.fallbackLabelstringDefault"Lightbox"The viewer's name where label is empty.idleDelaynumberDefault0How long the user can be idle before the header and footer hide, in
milliseconds. The attribute also takes a CSS time, such as 3s.labelstringDefault""The viewer's name, read by screen readers.loopbooleanDefaultfalseWhether moving past the last item returns to the first.maxZoomnumberDefault1How far a reader can zoom into the shown item, as a scale, such as 3.
1, the default, turns zooming off.nextLabelstringDefault"Next"The next control's accessible name.openbooleanWhether the element is open.previousLabelstringDefault"Previous"The previous control's accessible name.slideLabelstringDefault"{index} of {count}"The name of an item with no label of its own, with {index} and
{count} filled in, written in the locale.slideRoleLabelstringDefault"slide"The word screen readers announce in place of an item's role, set as
aria-roledescription. Translate it with the rest of your text, or empty
it to leave the role as group.statusLabelstringDefault"{index} of {count}"The status text that says which item is shown, with {index}, {count}
and the item's {label} filled in, the numbers written in the locale.zoomInLabelstringDefault"Zoom in"The zoom-in control's accessible name.zoomOutLabelstringDefault"Zoom out"The zoom-out control's accessible name.zoomStatusLabelstringDefault"Zoomed to {scale, number, percent}"What the live region says once a reader has stopped zooming. {scale, number, percent} writes the scale as a percentage the way the locale
writes one, such as 150%, or 150 % in French. {percent} is the same
scale as a whole number, for a sentence that places the sign itself. Empty
it to say nothing.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The items, which are <helix-headless-lightbox-item> elements.dismiss-iconReplaces the glyph inside the close control.footerContent below the item, such as a counter or a thumbnail strip.headerContent above the item, such as a title and a close button.next-iconReplaces the glyph inside the next control.previous-iconReplaces the glyph inside the previous control.zoom-in-iconReplaces the glyph inside the zoom-in control.zoom-out-iconReplaces the glyph inside the zoom-out control.
EventTypeDescriptioncloseEventFired when the viewer closes. The component dispatches it again from the host, because the dialog's own event does not leave the shadow root.helix-activateHelixActivateEventFired after the shown item changes, when the element already holds the new item.helix-before-activateHelixBeforeActivateEventFired before the shown item changes. Cancelable: cancel it to keep the current item. It is the only way to stop the change.helix-before-closeHelixBeforeCloseEventFired before the viewer closes. Cancelable.helix-before-openHelixBeforeOpenEventFired before the viewer opens. Cancelable.toggleToggleEventFired when the viewer opens or closes, with newState and oldState.
MethodTypeDescriptionclose() => voidCloses the viewer, unless a helix-before-close listener cancels it.next() => voidShows the next item. After the last item, it shows the first when loop
is set.previous() => voidShows the previous item. Before the first item, it shows the last when
loop is set.requestActive(next: string, cause: string) => booleanRequests a new shown item, and returns whether it moved.requestOpen(next: boolean) => booleanRequests that the element open or close, and returns whether the change
was applied.show() => voidOpens the viewer, which makes the rest of the page inert.toggleFullscreen() => voidMakes the viewer fill the screen, or exits fullscreen.toggleOpen() => booleanRequests the opposite of the current state.zoomTo(scale: number) => voidZooms the shown item to scale, held between 1 and max-zoom, about
the middle of the viewport.
PartDescriptioncounterThe place of the shown item in the set, drawn with counter.dialogThe native dialog element.dismissThe close control, drawn with controls.dismiss-markThe glyph on the close control, where none is slotted.footerThe slot the footer is in. It draws no box until you give it one.headerThe slot the header is in. It draws no box until you give it one.liveThe live region that announces which item is shown, and the scale once a reader has zoomed. Visually hidden in the styled tier.nextThe control that shows the next item, drawn with controls.next-markThe glyph on the next control, where none is slotted.previousThe control that shows the previous item, drawn with controls.previous-markThe glyph on the previous control, where none is slotted.viewportThe box the current item is shown in.zoom-inThe control that zooms in by half again, drawn with controls where max-zoom allows zooming.zoom-in-markThe glyph on the zoom-in control, where none is slotted.zoom-outThe control that zooms back out, drawn with controls where max-zoom allows zooming.zoom-out-markThe glyph on the zoom-out control, where none is slotted.
CSS PropertyDescription--lightbox-pan-xHow far the zoomed item is moved across from the middle of the viewport, in pixels, toward the right. Written only while zoomed.--lightbox-pan-yHow far the zoomed item is moved down from the middle of the viewport, in pixels. Written only while zoomed.--lightbox-zoomThe scale the shown item is zoomed to, such as 2. Written only while zoomed.
Custom stateDescriptionenteringFrom the moment the viewer opens until its entrance has finished.exitingFrom the moment the viewer closes until its exit has finished.fullscreenWhile the viewer fills the screen.idleThe user has been still long enough for the controls to hide.openWhile the viewer is open.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.zoomableWhile max-zoom lets a reader zoom.zoomedWhile the shown item is zoomed past its own size.
Itemhelix-headless-lightbox-itemOne item a lightbox can show, such as a picture, a video frame, or a chart.
PropTypeDescriptioncurrentbooleanDefaultfalseWhether this item is the one shown.labelstringDefault""The item's name. It names the item's group, and fills {label} in the
lightbox's status-label.valuestringDefault""The item's identifier. The root compares its active value against it.
Without one, the item is named by its place in the set, counted from 1.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The content to show.descriptionA line under the content that describes it.
PartDescriptionitemThe box the content is shown in.
Custom stateDescriptioncurrentThe item the lightbox is showing.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionGalleryA set of pictures shown over the page, moved through with the arrow keys.PreviewA set of pictures shown over the page, moved through with the arrow keys.PreviewA set of pictures shown over the page, moved through with the arrow keys.