Coral is a thoroughly developed design system widely adopted by developers and designers for creating beautiful and user-friendly Sea internal products.
Copyright © 2018-2026 Sea Labs
Blogs
All blogsLightbox
Designer doc
Similar to Dialog, Lightbox focus must be trapped, especially to prevent pressing Tab jumping out of the Lightbox. Supported keyboard interactions include Arrow Left and Right to navigate, and Escape to close.
Example
View code
Lightbox header can be added to display the title and LightboxItemsCount by passing in getTitleByIndex prop.
View code
Lightbox Controls
The component by default doesn’t include the Controls, rather they are optional and composable. So, it should be flexible enough in the future to add more tools like Rotate, Fit to Screen, etc. Though it might be slightly difficult to get started with those utilities, if a set of tools turns out are very frequent to use, we can always provide a higher level and easier to use API for it based on the current one.
For tools like Download, Share won’t be handled/provided by this component and needs the consumers to add the buttons themselves to that Utilities, because it’s too specific for Coral to handle that.
View code
Auto-hide controls
To allow user to focus on the lightbox content, controls can be auto-hidden when mouse cursor remains stationary over the content for a predefined period of time, using autoHideDelay prop. In this example, controls will be hidden after 3 seconds.
View code
Controlled
In this example, you can:
- Control which image is active through activeIndex prop
- Add your own Download function
View code
Customizing contents
Adding header
You can add your own custom components inside the overlay by overriding the default overlayElement prop. Below is an example how to add a header to the currently active image.
View code
Inline overlay
By default, overlay container is portaled to the root element, just below document.body. You can pass container prop as null to the customized LightboxOverlay in order to render it without portal.
View code
Animations
You can disable the zooming animation by specifying immediate prop to true.
View code
Integration with @seaweb/file-viewer
Lightbox can typically be used with file viewer to preview files besides images, such as Excel and PDF files. For unsupported file types, it is recommended to display a placeholder.
In this example, @seaweb/file-viewer package is used, you can view more examples and documentation here on how to use.
View code
Accessibility
There is no WAI-ARIA specification for Lightbox in W3C. However, an appropriate set of roles and labels for Lightbox are:
- The container’s role=“region”, and it has aria-live=“assertive” on the container. The result is, if the items are images with proper alt attribute, the lightbox will spell out the current image alt.
- Elements that only show on lightbox active should have aria-hidden=“true” when lightbox is inactive.
API
Lightbox
| Prop name | Type | Default | Description |
|---|---|---|---|
| activeIndex | number | ||
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| collapse | boolean | ||
| flipKey | string | ||
| getTitleByIndex | (activeIndex: number) => string | ||
| immediate | boolean | ||
| initialActiveIndex | number | ||
| onChange | (activeIndex: number) => void | ||
| overlayElement | ReactElement<any, string | JSXElementConstructor<any>> | ||
| theme | Theme<StyledTheme> | { onLightBg: { ...styledDefaultTheme, }, onDarkBg: { ...styledDefaultTheme, interactions: { bgNeutralGeneral: { hover: alp(palette.white, 0.1), press: alp(palette.white, 0.2), selected: alp(palette.white, 0.1), }, bgNeutralStrong: { hover: alp(palette.white, 0.1), press: alp(palette.white, 0.2), selected: alp(palette.white, 0.1), }, bgTintSolid: { hover: alp(palette.white, 0.15), press: alp(palette.white, 0.3), selected: alp(palette.white, 0.15), }, bgTintTransparent: { hover: 0.15, press: 0.3, selected: 0.15 }, border: { hover: alp(palette.white, 0.15), press: alp(palette.white, 0.3), selected: alp(palette.white, 0.15) }, disabled: 0.3, }, }, } |
LightboxArrowButton
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| colorType | ColorTypes | neuForeInverse1st | Set color based on theme. If color is specified, that prop is used instead of this. |
| direction | ArrowDirections | ||
| disabled | boolean | Equivalent to button's disabled property. | |
| gradientBorderProps | GradientBorderProps | ||
| keyboardClickKeys | string[] | ||
| leftIcon | ReactNode | Element before the label. Equivalent to element on the label with some margin. | |
| loading | boolean | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> | ||
| radius | number | ||
| rightIcon | ReactNode | Element after the label. Equivalent to element on the label with some margin. | |
| size | ButtonSizes | ||
| variant | ButtonVariants | Prefers naming it as variant because type is a known button html property. |
LightboxControls
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| elevationLevel | number | 3 |
LightboxHeader
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| closeButtonProps | IconButtonProps | ||
| getTitleByIndex | (activeIndex: number) => string | ||
| itemsCountProps | LightboxItemsCountProps | ||
| showItemsCount | boolean | true | |
| titleProps | TextProps |
LightboxItem
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| disabled | boolean | Equivalent to button's disabled property. | |
| index | number | ||
| inlineSize | number | 80 | |
| keyboardClickKeys | string[] | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> |
LightboxOverlay
| Prop name | Type | Default | Description |
|---|---|---|---|
| arrowButton | ReactElement<LightboxArrowButtonProps, string | JSXElementConstructor<any>> | <LightboxArrowButton /> | |
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| autoHideDelay | number | zoom/rotate controls, arrow buttons and header are hidden after this delay of no mouse activity defaults to 0 (no auto hide) | |
| container | HTMLElement | configs.getPortalContainer('Lightbox', 'container') | |
| disableFocusLock | boolean | ||
| disableScrollLock | boolean | ||
| elevationLevel | number | 3 | |
| header | ReactElement<LightboxHeaderProps, string | JSXElementConstructor<any>> |
LightboxPlaceholder
| Prop name | Type | Default | Description |
|---|---|---|---|
| actionProps | HTMLAttributes<HTMLDivElement> & { as?: any; ref?: HTMLDivElement; } | ||
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| containerProps | HTMLAttributes<HTMLDivElement> | ||
| description | ReactNode | ||
| descriptionProps | HTMLAttributes<HTMLParagraphElement> & { as?: any; ref?: HTMLParagraphElement; } | ||
| height | Height<string | number> | ||
| image | ReactNode | NextImgProps | ||
| imageProps | ImgHTMLAttributes<HTMLImageElement> & { as?: any; ref?: HTMLImageElement; } | ||
| imageSize | Height<string | number> | Will not applied if image is a ReactNode | |
| maxWidth | MaxWidth<string | number> | ||
| offsetTop | MarginTop<string | number> | ||
| title | ReactNode | ||
| titleProps | HTMLAttributes<HTMLDivElement> & { as?: any; ref?: HTMLDivElement; } |
LightboxItemsCount
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. |
LightboxTransform
| Prop name | Type | Default | Description |
|---|---|---|---|
| initialRotation | Rotation | 0 | |
| initialScale | number | 1 | |
| initialTranslate | Translate | { x: 0, y: 0 } | |
| onRotationChange | (rotation: Rotation) => void | ||
| onScaleChange | (scale: number) => void | ||
| onTranslateChange | (translate: Translate) => void | ||
| rotation | Rotation | ||
| scale | number | ||
| scaleIndicatorDelay | number | 1000 | |
| showScaleIndicator | boolean | ||
| translate | Translate | ||
| zoomSteps | number[] | [0.1, 0.25, 0.4, 0.6, 0.8, 1, 1.2, 1.5, 2, 3, 4, 6, 8, 16] |
LightboxTransformControls
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| colorType | ColorTypes | neuForeInverse1st | Set color based on theme. If color is specified, that prop is used instead of this. |
| disabled | boolean | Equivalent to button's disabled property. | |
| gradientBorderProps | GradientBorderProps | ||
| keyboardClickKeys | string[] | ||
| loading | boolean | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> | ||
| radius | string | ||
| rotationInterval | number | -90 | |
| size | IconButtonSizes | ||
| tooltip | ReactNode | ||
| tooltipProps | Omit<TooltipProps, "title" | "children"> | ||
| variant | IconButtonVariants |
useLightboxTransformItem
| Prop name | Type | Default | Description |
|---|---|---|---|
| onDrag | Handler<"drag"> | ||
| onDragEnd | Handler<"drag"> & DragEventHandler<Element> | ||
| onDragStart | Handler<"drag"> & DragEventHandler<Element> | ||
| onHover | Handler<"move"> | ||
| onMove | Handler<"move"> | ||
| onMoveEnd | Handler<"move"> | ||
| onMoveStart | Handler<"move"> | ||
| onPinch | Handler<"pinch"> | ||
| onPinchEnd | Handler<"pinch"> | ||
| onPinchStart | Handler<"pinch"> | ||
| onScroll | Handler<"scroll"> | ||
| onScrollEnd | Handler<"scroll"> | ||
| onScrollStart | Handler<"scroll"> | ||
| onWheel | Handler<"wheel"> | ||
| onWheelEnd | Handler<"wheel"> | ||
| onWheelStart | Handler<"wheel"> |