Overview
The ImageSourceEditor family provides a complete solution for managing multiple images. It includes an editor component for uploading, reordering, and editing images, plus gallery and carousel components for display. Built with dnd-kit for drag-drop reordering and integrates with the Lightbox component for full-screen viewing.
Key Features
- Upload images via dropzone or add external URLs
- Drag-and-drop reordering with dnd-kit
- Edit alt text and captions for accessibility
- Crop and position images with visual editor
- Gallery display with configurable columns and sizing
- Carousel display with autoplay and navigation
- Lightbox integration for full-screen viewing
- Annotation overlay support for image hotspots
Module Exports
The image-source-editor module exports multiple related components:
| Export | Purpose |
|---|---|
ImageSourceEditor | Editor for managing images (upload, URL, reorder, edit, crop) |
ImageGallery | Grid-based image display with lightbox |
ImageCarousel | Slideshow display with navigation and autoplay |
ImageCropDialog | Dialog for cropping and positioning images |
ImageSource | Type definition for image data structure |
Examples
ImageSourceEditor
Upload images via dropzone or external URL, then reorder, edit, or crop them.
Snowy mountain peaks at sunrise
Snowy mountain peaks at sunrise
Peaceful ocean waves
Peaceful ocean waves
2 images added. Drag to reorder, click pencil to edit, or crop icon to adjust position.
The editor supports uploading via drag-drop or file selection, adding external URLs, and managing up to 10 images. Each image can have alt text (required for accessibility), captions, and custom positioning.
ImageGallery
Grid layout with configurable columns, sizing modes, and lightbox integration.
Snowy mountain peaks at sunrise
Peaceful ocean waves
Golden autumn forest trail
Dramatic sunset colors
The gallery displays images in a responsive grid. Click any image to open it in the lightbox. Configure the number of columns (1-4), sizing mode (fit, fill, contain), and maximum height.
ImageCarousel
Slideshow with navigation arrows, dot indicators, and optional autoplay.
Snowy mountain peaks at sunrise - a breathtaking view of nature
Use arrow keys or click the navigation buttons to move between images. Click on the image to open in lightbox.
The carousel shows one image at a time with navigation controls. Use arrow keys or click the navigation buttons to move between images. Enable autoplay for automatic transitions.
Props Reference
ImageSourceEditorProps
| Prop | Type | Default | Description |
|---|---|---|---|
value | ImageSource[] | required | Current list of images |
onChange | (images: ImageSource[]) => void | required | Callback when images change |
scopeType | ScopeType | - | Scope type for file operations (PROGRAM, PROJECT) |
scopeId | string | - | Scope ID for file operations |
purpose | FilePurpose | DESIGN | File purpose for uploaded images |
accessLevel | FileAccess | PUBLIC | Access level for uploaded images |
disabled | boolean | false | Disable all interactions |
ImageGalleryProps
| Prop | Type | Default | Description |
|---|---|---|---|
images | ImageSource[] | required | Images to display in the gallery |
columns | 1 | 2 | 3 | 4 | 2 | Number of grid columns |
sizing | 'fit' | 'fill' | 'contain' | 'fill' | Image sizing mode (fit, fill, or contain) |
maxHeight | 'small' | 'medium' | 'large' | 'full' | 'medium' | Maximum height for images |
showCaptions | boolean | false | Show captions below images |
enableLightbox | boolean | true | Enable lightbox on click |
enableAnnotations | boolean | true | Display annotation overlays |
className | string | - | Additional className for the container |
ImageCarouselProps
| Prop | Type | Default | Description |
|---|---|---|---|
images | ImageSource[] | required | Images to display in the carousel |
sizing | 'fit' | 'fill' | 'contain' | 'fill' | Image sizing mode |
maxHeight | 'small' | 'medium' | 'large' | 'full' | 'medium' | Maximum height for images |
showCaptions | boolean | false | Show captions below current image |
enableLightbox | boolean | true | Enable lightbox on click |
enableAnnotations | boolean | true | Display annotation overlays |
autoplay | boolean | false | Auto-advance slides |
autoplayInterval | number | 5 | Autoplay interval in seconds |
className | string | - | Additional className for the container |
ImageSource Type
| Prop | Type | Description |
|---|---|---|
id | string | Unique identifier for the image |
type | 'blob' | 'url' | Source type (uploaded blob or external URL) |
src | string | Image URL |
alt | string | Alt text for accessibility |
thumbnailSrc | string | Optional thumbnail URL for galleries |
caption | string | Optional caption text |
width | number | Original image width |
height | number | Original image height |
fileSizeBytes | number | File size in bytes (blob uploads only) |
position | ImagePosition | Crop/position data { x, y, scale } |
annotations | Annotation[] | Array of annotation hotspots |
Usage
import {
ImageSourceEditor,
ImageGallery,
ImageCarousel,
type ImageSource,
} from '@/ui/components/image-source-editor';
// Editor for managing images
const [images, setImages] = useState<ImageSource[]>([]);
<ImageSourceEditor
value={images}
onChange={setImages}
scopeType="PROJECT"
scopeId={projectId}
/>
// Gallery display (grid layout)
<ImageGallery
images={images}
columns={3}
sizing="fill"
maxHeight="medium"
showCaptions
enableLightbox
/>
// Carousel display (slideshow)
<ImageCarousel
images={images}
sizing="fill"
maxHeight="large"
showCaptions
autoplay
autoplayInterval={5}
/>