Coral is a thoroughly developed design system widely adopted by developers and designers for creating beautiful and user-friendly Sea internal products.
Copyright © 2018-2025 Sea Labs
Lightbox
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 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
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
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 | ||
| immediate | boolean | ||
| initialActiveIndex | number | ||
| onChange | (activeIndex: number) => void | ||
| overlayElement | ReactElement<any, string | JSXElementConstructor<any>> | <LightboxOverlay /> | |
| 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. | |
| 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. |
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. | |
| container | HTMLElement | configs.getPortalContainer('Lightbox', 'container') | |
| disableFocusLock | boolean | ||
| disableScrollLock | boolean | ||
| elevationLevel | number | 3 |
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. |
LightboxZoom
| Prop name | Type | Default | Description |
|---|---|---|---|
| initialScale | number | 1 | |
| initialTranslate | Translate | { x: 0, y: 0 } | |
| onScaleChange | (scale: number) => void | ||
| onTranslateChange | (translate: Translate) => void | ||
| scale | number | ||
| translate | Translate |
LightboxZoomControls
| 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 | neuFore1st | Set color based on theme. If color is specified, that prop is used instead of this. |
| disabled | boolean | Equivalent to button's disabled property. | |
| 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. |
useLightboxZoomItem
| 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"> |